> ## 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={null}
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={null}
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.

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