Skip to main content

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.

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.

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.

Metro bundling errors after adding withAppilots()​

This is usually a missing or invalid .appilotsrc. The plugin warns and falls through to your unmodified Metro config if the file is missing — so the app still runs, but auto-config won't kick in and you'll likely hit "No config found" at runtime instead.

Fix: confirm .appilotsrc exists at your project root and is valid JSON. See CLI: Configuration for the expected shape.

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?​

Last updated on