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.

​
A Blender project does not appear

  1. Check get_execution_context and ar_blender capabilities. Install or locate Blender on that execution host. For portable installations, pass the full executable path or configure NGRAM_BLENDER_EXECUTABLE there.
  2. Check the project’s status. A script must publish at least one checkpoint. The host’s successful export is separate from the browser’s asset readiness.
  3. Inspect ar_world observe for the asset ID, error, and current revision. Use Refresh project or Reload asset in Objects as appropriate. Previews wait while the object is held or its updates are paused.
  4. If the project was authored without a connected surface, use ar_blender show after connecting. A deleted live object is not automatically respawned by later previews.
An unknown blender execution action indicates an older or unsupported execution backend. Update the Entity worker, execution backend, and Spatial gateway together. The full workflow is in Blender.

​
A creation does not animate

Check Resume creations, then inspect the program’s status and error in Objects. Restored programs start paused; missing objects or a worker timeout can leave a program failed. A scene toggle can also intentionally keep a running program still. Local behavior does not need a new agent response each frame.

​
Saved creations fail to load

An orphaned program can fail while the rest of the scene loads. Repair its object scope before resuming it. If the world document itself fails to restore, automatic saving is blocked to preserve the original data. Import a repaired document rather than clearing browser storage. Browser world exports and Blender project backups are separate; see persistence.

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