> For the complete documentation index, see [llms.txt](https://doc.faceplugin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.faceplugin.com/help/resources/troubleshooting.md).

# Troubleshooting

Troubleshoot Faceplugin SDK demos. Missing AAR or frameworks, wrong app id licenses, Docker shm-size, Yarn 3 on React Native, and cameras that stay black on emulators.

Start here when a Faceplugin demo never reaches **Ready**, the camera stays black, or HTTP process calls fail after Docker starts.

## Home never shows Ready / tiles stay locked

1. Native runtime missing or nested in a subfolder. Check the exact AAR / framework path in that SDK's platform guide.
2. Wrong application id — demo license key only matches the sample id.
3. `init` returned 1–4. See [Status codes](/help/resources/status-codes.md).
4. Called activate/init on the UI thread (Android) or before the binary was packaged (hot reload is not enough).

## Camera black / crash

Physical device, `CAMERA` permission / `NSCameraUsageDescription`, arm64. Document Reader and Face plugins often filter `arm64-v8a` only in the demo.

## Docker starts then process calls fail

Activate with `POST /api/activate`. Detached Compose does not prompt. `--shm-size` too small for Document Reader (`dcr.fpk`). Privileged + machine-id volume as in the README. Sizing and Docker flags: [Hosting requirements](/integration/deploy-and-host/hosting-requirements.md). Endpoint contracts: [HTTP API](/integration/http-api.md).

## `lib/cpu` “file not found”

You unzipped into `lib/cpu/FolderName/`. Files must sit **directly** in `cpu/`.

## React Native `npm install` broke the repo

Use **Yarn 3** as `packageManager`. npm workspaces are not supported at the root.

## Ionic / Flutter in the browser

`ionic serve` and Flutter web do not load the engine. Open Android Studio / Xcode after `cap sync` / `flutter run`.

## Two products in one APK / one `lib/`

Do not dump a second product’s Google Drive runtime into another product’s `lib/cpu/`. Run separate servers instead. See [Architecture](/integration/deploy-and-host/architecture.md).

## Still stuck

Email <info@faceplugin.com> with: OS, GitHub repo name, activate/init code, and whether you used Docker or Google Drive.

### Related documentation

* [HTTP API](/integration/http-api.md) · [Hosting requirements](/integration/deploy-and-host/hosting-requirements.md) · [Architecture](/integration/deploy-and-host/architecture.md)
* [FAQ](/help/resources/faq.md) · [Glossary](/help/resources/glossary.md) · [Status codes](/help/resources/status-codes.md) · [Try it](/getting-started/try-it.md)
* [Request a License](/help/request-a-license-and-support.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.faceplugin.com/help/resources/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.