> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngram.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Find the failing boundary

> Work from the runtime outward: declaration, provider, storage, bridge, and surface.

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:

```bash theme={"theme":"github-light-default"}
uv run ngram ask rook "Reply with one sentence."
```

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:

```bash theme={"theme":"github-light-default"}
uv run ngram lab doctor rook
```

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](/guides/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](/spatial/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](/deployment/persistence#spatial-artifacts).

## 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](/deployment/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.