Skip to main content
Start with the smallest failing operation. A rendered avatar does not prove inference works; a provider response does not prove tool execution or memory storage works.

​
The Entity does not answer

  1. Check whether inference is paused. Resume in spatial or with Telegram /resume from an operator account.
  2. Confirm the Entity process is running. Closing the terminal running talk, run, or worker can stop that process.
  3. Try a single foreground request to separate inference from platform delivery:
This can use paid inference. If it fails, inspect the provider configuration and runtime log before debugging Telegram or WebXR.

​
Hosted chat works, but memory fails

Memory retrieval also needs embeddings. Confirm NGRAM_EMBEDDING_MODEL, its provider support, and the required output dimensions. A valid chat model ID is not an embedding model ID. The lab checks embedding readiness during setup. Run:
Matching vector width is necessary, but embeddings from different models can still occupy different semantic spaces. Keep the embedding model stable for an existing memory store unless you have a deliberate migration plan.

​
The model keeps working

Use Pause inference to stop new model requests across the Entity. Use Stop response or Esc to interrupt spatial work. Do not rely on /wakequiet, closing a tab, or setting autonomy.enabled: false as a global inference stop. If you need to stop a deployment regardless of surface connectivity, stop its worker in the hosting platform. See usage and controls.

​
Context looks full or compaction fails

Use /context and /compact status in Telegram, or inspect the spatial context control. The displayed usage is approximate. The active provider’s effective working budget can differ from the base YAML context setting. /compact needs enough older history to summarize and requires running inference. A short conversation can legitimately return “Nothing to compact yet.” On provider failure, retry after restoring inference; /reset discards live context and is not a substitute for successful summarization.

​
The shell loads, but the Entity is disconnected

Confirm the shell uses binding.type: ngram_entity, then check:
  • The Entity process is running with its bridge enabled.
  • The shell’s bridge URL reaches the right host and port.
  • The bearer credential agrees on both sides.
  • The browser-facing gateway can reach the Entity bridge from its own host.
For the hosted lab, use uv run ngram lab doctor rook. For conventional pairing, rerun uv run ngram ar setup rook --target local and review the generated private configuration.

​
A spatial tool reports success, but nothing appears

Inspect the surface with ar_inspect_surface. Check the actual tool result, the connected session, the current view, and the requested object ID. Some dispatch paths acknowledge queueing; that is not proof that every browser has rendered the action. Movement, panels, physics objects, and generated motion have different prerequisites. An external motion request requires a configured motion backend. Headset tracking is unavailable in an ordinary desktop session.

​
Quest cannot connect

Use the host’s reachable LAN address, keep the host and headset on the intended trusted network, and check the firewall. WebXR requires an appropriate secure browser context. Follow the URL and certificate guidance printed by the lab supervisor for your environment. Do not put a loopback URL from your computer into the headset: on the headset, localhost refers to the headset itself.

​
State disappears after redeploy

Check both structured memory and disk paths. A Postgres database does not preserve files on an ephemeral container filesystem. Verify that the volume is mounted where NGRAM_EXECUTION_WORKSPACE_DIR points and that the runtime account can write there. See persistence for the full storage map.

​
Share a useful bug report

Include the app commit, operating system, deployment mode, surface, provider name, model ID, expected behavior, and a short reproduction. Include the relevant error and timestamp, after removing keys, private URLs, conversation content, and personal identifiers.