Troubleshoot the EDOT React Native SDK

Use this guide to resolve React Native-specific setup, build, and startup problems with Elastic Distribution of OpenTelemetry React Native. Check the requirements before troubleshooting.

In the messages below, placeholders such as <path> and <key> stand for values from your project.

setup-android or setup-ios exits with an error and prints:

No file was changed.

Android setup reports a missing file or insertion point:

<path> was not found.
<path> has no line <anchor>.

iOS setup can report:

The iOS project does not match the supported bare React Native template layout.

The following diagnostics identify the layout problem:

package.json must declare a react-native dependency.
Cannot read package.json: <reason>
Expected exactly one iOS Xcode project, found <n>.
Cannot read the iOS Xcode project: <reason>
Missing supported Podfile anchor matching <pattern>.
Cannot read ios/Podfile: <reason>

An unreadable project structure or an unexpected number of application targets can also produce:

Cannot parse <project>: <reason>
Expected exactly one application target in <project>, found <n>.

The command is running outside the application root, a required file is missing, or the project differs from the supported bare React Native template.

Run the command from the application's root directory. Check the named file and diagnostic. For a customized project, follow Manual host setup fallback and the manual steps printed by the command. Review your changes before building the app.

The setup command prints:

Failed to update <path>: <reason>

The command cannot write the named file. The reason in the message identifies the filesystem error.

Resolve the reported filesystem error, check git diff for any edits already made, and rerun the setup command. If you apply the edits yourself, use Manual host setup fallback.

The Android build stops with:

EDOT React Native: variant '<variant>' has minSdk <n> without Java 8 library desugaring. Raise minSdk to 26, or keep minSdk at 24 or higher and enable Java 8 library desugaring with coreLibraryDesugaringEnabled and a coreLibraryDesugaring dependency.

Below API level 24, the Android manifest merger reports a minimum SDK conflict.

The affected variant does not meet the Android API requirements.

Raise the app's minSdk to 26, or use API level 24 or later with Java 8 library desugaring. Check the minSdk for the variant named in the error.

The Android build warns:

EDOT React Native: <path>/elastic-otel-config.json was not found. ElasticOtelReactNative.initialize(this) fails at startup without it.

At startup, initialization throws one of these messages:

elastic-otel-config.json was not found in the app assets. Create it at the React Native project root and apply the bridge's Gradle script in android/app/build.gradle.
elastic-otel-config.json was not found in the app bundle. Create it at the React Native project root, run setup-ios, and check that the file is in the app target's Copy Bundle Resources build phase.

npx expo prebuild can fail with:

elastic-otel-config.json was not found. Create it at the project root, next to package.json.

The configuration file is absent from the application root or was not included in the app build.

Create the file as described in Configuration file. For a bare app, complete setup-android or setup-ios and the manual host setup as needed. For Expo, follow Set up an Expo app. Rebuild the app after correcting the file or project setup.

initialize() throws BootstrapException. JSON structure, key, and type errors include:

elastic-otel-config.json must contain one JSON object: <detail>
elastic-otel-config.json contains the unknown key <key>.
elastic-otel-config.json is missing the required key exportUrl.
elastic-otel-config.json key <key> must be a string.
elastic-otel-config.json key <key> must be a number.
elastic-otel-config.json key exportProtocol must be "http" or "grpc", not "<value>".
elastic-otel-config.json key resourceAttributes must be an object.
elastic-otel-config.json key resourceAttributes.<key> must be a string.

Export URL errors include:

An OTLP export URL is required.
The OTLP export URL is invalid.
The OTLP export URL must use http or https.
The OTLP export URL must include a host.
The OTLP base URL must not include a query or fragment.
The OTLP base URL must not include a signal-specific path.

Sampling, service identity, resource attribute, and API key errors include:

The session sample rate must be between 0 and 1.
The resource attribute service.name is required.
Resource attribute keys must not be blank.
The resource attribute <key> must not be blank.
The resource attribute key <key> must be at most 255 printable ASCII characters.
The API key must not be blank.

The configuration file or configuration supplied in code does not satisfy the validation rules. Initialization stops before telemetry starts.

Correct the setting named in the error using the configuration reference. See Initialization and errors for error handling. Rebuild the app after changing its configuration file.

Initialization throws one of these messages:

EDOT Android has already been initialized.
EDOT iOS has already been initialized.
EDOT iOS was initialized outside @elastic/otel-react-native.
EDOT iOS failed to initialize.

The first two messages indicate a duplicate initialization call. On iOS, the third indicates that the app also initializes EDOT iOS separately. The last message indicates that iOS initialization did not succeed.

Check the app's startup code against Bootstrap before React Native and Initialization and errors. Keep one EDOT React Native initialization call and remove separate EDOT iOS initialization. If iOS initialization fails, inspect the startup logs and use the iOS troubleshooting guide for native SDK problems.

A JavaScript call throws:

@elastic/otel-react-native is unavailable. Native autolinking must be enabled and the app rebuilt.

Manual telemetry calls can also reject with code E_ELASTIC_OTEL_REACT_NATIVE and one of these messages:

EDOT Android is not initialized. Bootstrap it in Application.onCreate.
EDOT iOS is not initialized. Bootstrap it in AppDelegate before React Native starts.

The app build does not include the package's native module, or initialization has not completed successfully before the JavaScript call.

Enable native autolinking, complete the platform's getting-started steps, and rebuild the native app. Reloading JavaScript does not rebuild the app. For an initialization rejection, check the startup logs for a configuration error and confirm that bootstrap runs before React Native starts.

npx expo prebuild fails with:

<file> has no <anchor>.
<file> is not Kotlin. Add the bootstrap lines from the getting-started guide manually.
<file> is not Swift. Add the bootstrap lines from the getting-started guide manually.

The config plugin edits the Kotlin MainApplication, Swift AppDelegate, and Gradle files that the Expo template generates, and inserts its lines after lines from that template. The error means a generated file no longer matches the template, for example because the android or ios directory was edited by hand or generated by an earlier Expo SDK.

Check that the app meets the Expo SDK requirement, then regenerate the native directories with npx expo prebuild --clean. --clean deletes the android and ios directories before it generates them again, so changes made by hand in those directories are lost.

Don't fix these errors by editing the generated files: --clean discards those edits, and the language errors persist while the config plugin is listed in expo.plugins, even though their message suggests adding the bootstrap lines manually.

Metro reports a TypeError naming a Babel plugin option, for example:

Unknown option interactions.<name>.
interactions.components must be an array.
interactions.components[0].name is required.
interactions.components[0] must list an instrumentation in instrumentations or set enabled: false.
interactions.widgetId[1] follows @component, which always has a value, so it is never used.

The plugin options contain an unknown key, an invalid type, an incomplete or duplicate component entry, an unsupported instrumentation or macro, or a source listed after @component.

Correct the option named in the error using the Babel plugin configuration. Restart Metro with a cleared cache after changing the options.

Tapping a component produces no widget tap event.

The bundle does not include the Babel plugin changes, tap instrumentation is turned off, or the element does not match the plugin's instrumentation rules.

Check the widget tap setup and supported components. Reset the Metro cache with npx react-native start --reset-cache or npx expo start --clear. Use the debug: true report to identify skipped elements.

For problems outside React Native setup and startup, use these guides:

If the problem persists, existing Elastic customers with a support contract can open a ticket in the Elastic Support portal. Other users can post in the APM discuss forum.