Troubleshooting

Common problems when integrating @appilots/sdk, and how to fix them.

"AppilotsProvider: No config found"

This means neither a config prop nor .appilotsrc auto-config resolved a projectId. AppilotsProvider needs one or the other before it can talk to your project.

Fix, one of:

• Pass config explicitly:

  <AppilotsProvider config={{ projectId: 'proj_xxxxxxxx', apiKey: 'ak_xxxxxxxxxxxx' }}>

• Set up the Metro plugin and a .appilotsrc file at your project root so config resolves automatically. See CLI: Configuration for the file format and SDK Overview for wiring withAppilots() into metro.config.js.

  Already did that and still see this error? Check your entry file for:

  index.js

  import '@appilots/auto-init'; // must be the first import

  withAppilots() generates the module that this specifier resolves to, but it does not import it for you. With metro.config.js and .appilotsrc both correct and this line missing, the generated module never enters the bundle, global.__APPILOTS_RC__ is never set, and the provider reports exactly the same "No config found" as if you had configured nothing at all.

"No safe area value available" from inside AppilotsChat

The full error — No safe area value available. Make sure you are rendering SafeAreaProvider at the top of your app. — comes from react-native-safe-area-context, with AppilotsChat in the stack.

AppilotsChat is a floating overlay and calls useSafeAreaInsets() to stay clear of the notch and the home indicator, so it needs a SafeAreaProvider above it in the tree. The usual cause is not a missing provider but a misplaced one — it sits inside the navigator while the chat is rendered as a sibling next to it:

// ✗ AppilotsChat is outside the SafeAreaProvider
<AppilotsProvider>
  <AppilotsNavigationContainer>
    <SafeAreaProvider>{/* ... */}</SafeAreaProvider>
  </AppilotsNavigationContainer>
  <AppilotsChat />
</AppilotsProvider>

Hoist the provider to the root instead of adding a second one:

// ✓
<SafeAreaProvider>
  <AppilotsProvider>
    <AppilotsNavigationContainer>{/* ... */}</AppilotsNavigationContainer>
    <AppilotsChat />
  </AppilotsProvider>
</SafeAreaProvider>

Chat opens, but the agent can't see or operate a screen

Usually one of three things:

1. The screen isn't registered. Every screen the agent should know about needs a registerScreen call — see Navigation.
2. The screen's fields or buttons aren't registered. Auto-tracking, the registration hooks, or the HOCs need to be wired up for that screen — see Registering elements.
3. The MCP document is stale. If the app shipped new screens or fields but nobody re-ran appilots sync, the agent is working from an outdated map of your app. See CLI Usage.

Adding explicit testIDs to your interactive elements makes auto-tracking noticeably more reliable — it's the first ID auto-tracking looks for.

The agent sees nothing at all, on every screen

If no screen has any content — not one text, button, or field — the SDK probably never reached your React tree, and the problem is not registration. Check it directly:

import { getIntrospectionDiagnostics } from '@appilots/sdk';

getIntrospectionDiagnostics();
// { captured: true, failureReason: null, reactVersion: null, failureCount: 0 }

captured: false with a failureReason means every snapshot this session is empty:

failureReason	captured	What happened
never-mounted	false	A snapshot was requested before <AppilotsProvider> committed, or from outside it. Make sure the provider wraps the tree you expect the agent to see.
sentinel-missing-internals	false	The SDK mounted inside your tree but React did not expose the fiber it needs. This means a React version the SDK has not been validated against — reactVersion tells you which. Open an issue with that value.
render-crashed	false	The SDK's own chat surface threw and its error boundary degraded it. This one is our bug — please open an issue.
names-mangled	true	Your bundle renamed the React Native components the SDK matches by name. Detection still works through accessibility roles and component shape, but less precisely. Keep keep_fnames/keep_classnames in your Metro minifierConfig — withAppilots() sets them for you.
walk-recognized-nothing	true	The SDK reached your tree and walked a real screen's worth of it without recognizing a single element. The screen was not empty; the reading was. Run appilotsSelfCheck() below — it says which detector died.

The same condition is emitted on the event bus once, at provider mount, so you can forward it from production instead of waiting for a bug report:

const { subscribe } = useAppilotsContext();

useEffect(
  () =>
    subscribe((event) => {
      if (event.type === 'sdk:introspection:unavailable') {
        myCrashReporter.captureMessage('Appilots introspection unavailable', event.data);
      }
    }),
  [subscribe],
);

Getting a full picture from a release build

getIntrospectionDiagnostics() answers whether the SDK reached your React tree. appilotsSelfCheck() answers what it understood once it got there — which is the question you need when the agent reports an empty screen that plainly is not empty.

It works in a Release build, needs no console and no debugger, and is safe to call at any time: it walks the tree once and changes nothing.

import { appilotsSelfCheck } from '@appilots/sdk';

// Wire this to a hidden dev-menu button, then paste the output into your
// bug report.
console.log(JSON.stringify(appilotsSelfCheck(), null, 2));

{
  "sdkVersion": "0.9.0",
  "reactVersion": "18.3.1",
  "route": "Settings",
  "introspection": {
    "captured": true,
    "failureReason": null,
    "reactVersion": null,
    "failureCount": 0
  },
  "autoTracking": {
    "enabled": true,
    "createElementPatched": true,
    "jsxRuntimePatched": true,
    "jsxDevRuntimePatched": false,
    "interceptionActive": true
  },
  "walk": { "visitedFibers": 4127, "skippedHidden": 12, "elapsedMs": 9 },
  "detectors": {
    "Text": 0,
    "TextInput": 0,
    "Switch": 0,
    "ActivityIndicator": 0,
    "Modal": 0,
    "adjustable": 0,
    "pressable": 0,
    "listContainers": 0
  },
  "registry": { "fields": 4, "toggles": 1, "sliders": 0, "targets": 6, "lists": 1, "elements": 0 },
  "nameMangling": null
}

How to read it:

What you see	What it means
walk.visitedFibers large, every detectors count 0	The tree is there and the SDK stopped recognizing it — the case shown above. Check nameMangling first.
detectors.Text > 0 but detectors.Switch === 0 on a screen with a switch	One detector, not the whole walker. Open an issue naming the detector and the component you use.
registry counts high, detectors all 0	Auto-tracking is registering components the walk cannot find.
registry counts 0 and autoTracking.enabled: false	enableAppilotsAutoTracking() never ran. Same empty screen, completely different fix.
autoTracking.enabled: true but jsxRuntimePatched: false	Your bundler resolved a different copy of react/jsx-runtime. Wire withAppilots() into metro.config.js — see SDK Overview.

detectors counts what the walker recognized, which is not the same as what reached the agent: an empty <Text> and two identical unlabelled buttons are recognitions the snapshot then drops. A gap between the two is normal; all zeros on a populated screen is not.

Fields register, but the agent can't find them by name

Check what id is actually being used. Auto-tracking derives an element's id by checking, in order:

1. testID
2. nativeID / id
3. accessibilityLabel
4. name
5. placeholder
6. A non-"off" autoComplete value

If none of these are present, auto-tracking falls back to a best-effort guess and logs a warning. Enable debug: true locally (see below) to see registration diagnostics in the console.

Fix: add an explicit testID to the element — it's checked first and is the most reliable signal.

.appilotsrc not found when Metro starts

withAppilots() reads .appilotsrc to generate the module that import '@appilots/auto-init' resolves to, so it fails the build when the file is missing rather than continuing without auto-config. The error names the path it looked at.

Fix: create .appilotsrc at your project root — appilots init, or copy your project's .appilotsrc.example. See CLI: Configuration for the expected shape. Invalid JSON fails the same way.

If your project deliberately has no .appilotsrc, pass withAppilots(config, { optional: true }), drop the import '@appilots/auto-init' line, and pass the config to <AppilotsProvider config={…}> yourself.

Before SDK 0.9 the plugin only warned here and returned your Metro config unmodified. The bundle then failed on the unresolvable @appilots/auto-init import, or the app booted without auto-config and hit "No config found" at runtime.

Peer dependency errors

react-native-safe-area-context and react-native-svg are required peer dependencies, not optional ones. If you see resolution errors for either, install them directly — see Installation for minimum versions.

Enabling debug output

<AppilotsProvider config={{ debug: true }}>

or in .appilotsrc:

{ "debug": true }

This turns on local diagnostic console logging you can use to troubleshoot your own integration — screen registration, action execution, and similar SDK-side events. Treat it as diagnostic output for local debugging rather than a stable, parseable format.

Multiple <AppilotsChat/> instances / multi-tenant apps

If your app needs more than one isolated chat instance — for example, separate registries per tenant or per session — createComponentRegistry() plus <AppilotsRegistryProvider value={...}> let you scope registration to a subtree instead of sharing the global singleton registry. This is an advanced, uncommon setup; see Registering elements for the registry APIs.

Still stuck?

• Guides: Your First Integration — a full walkthrough from install to a working chat.
• API Reference: Errors — if the problem looks network- or auth-related rather than SDK-side.