Troubleshooting.
Real messages, what they mean.
Most problems are the native build or the phone's memory.
01Build
iOS: "Building the on-device AI engine failed"
The Podfile runs packages/pocket_llm/tool/build_ios.sh. Run it yourself to see the error; its logs are in packages/pocket_llm/build-cache/ios.*.log. Usually CMake is missing (brew install cmake) or Xcode command line tools are not selected (sudo xcode-select -s /Applications/Xcode.app).
iOS simulator: "does not contain architectures x86_64"
The engine is arm64-only. Use an Apple-silicon Mac; the project already excludes x86_64 for the simulator.
Android: CMake or NDK not found
Install NDK 28.2.13676358 and CMake 3.22.1 in Android Studio > SDK Manager > SDK Tools.
The first build takes long
It compiles llama.cpp and whisper.cpp (several minutes). Later builds reuse the result.
02Models
"This file is not a valid model."
The downloaded file's sha256 or GGUF header did not match the catalog, so it was deleted. Check the url (it must be the /resolve/main/ link, not the web page) and the sha256 and sizeBytes of the line.
"No connection. The download will continue where it stopped."
The download is paused and kept; tap Resume when online.
"This phone has less memory than this model needs."
The phone's RAM is below the model's minRamGb. Use a smaller model.
"Not enough free space"
The phone needs the model size plus 10 % free.
The app closes while answering
The phone ran out of memory. Use a smaller model or lower nCtx in the catalog line.
Replies are strange or repeat
Small models make mistakes; try a larger model, lower Creativity in Settings, or a clearer assistant style. Qwen3 lines need "systemSuffix":" /no_think".
03Features
"No readable text found in this PDF."
The PDF is scanned (images only). The app reads the text layer; it does not do OCR.
Photo and voice buttons say to download a model
Download SmolVLM (photos) or Whisper base (voice) in Models.
The console change does not show in the app
The app reads the config at start; restart it. Check the app was built with API_BASE_URL and the console answers at /v1/config.
Ads do not show
See Ads.