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

# Troubleshooting

> Symptom-first fixes for MCP, Docker, search, permissions, KG health, and local startup issues.

# Troubleshooting

You can use this page when Pulse does not start, an agent cannot connect, permissions block a tool, or the KG reports unhealthy status.

## MCP connection issues

| Symptom                                  | Likely cause                                             | Fix                                                            |
| ---------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------- |
| Host cannot reach MCP in Docker          | `MCP_HOST` is bound to `127.0.0.1` inside the container. | Set `MCP_HOST=0.0.0.0` and restart.                            |
| Tool calls return authentication errors  | Missing or stale API key.                                | Re-run `okto-pulse init --agents` and update the agent config. |
| Browser probe shows `406 Not Acceptable` | Raw HTTP probe did not negotiate MCP stream transport.   | Test with an MCP client, not a generic GET request.            |

## Search returns 0 results

Algolia results depend on crawler freshness and DNS. If the docs site recently moved, trigger or wait for the crawler, then verify the exact page URL directly.

## Pages 404

Check that the page exists as an `.mdx` file, appears in `docs.json` navigation when it should, and has deployed from the current `main` commit.

## KG health shows unhealthy

Start with:

```text theme={null}
okto_pulse_kg_health(board_id="...")
```

If dead-letter count is non-zero, inspect DLQ before rerunning backfill.

## `okto-pulse init` fails

Common causes are port conflicts, unwritable working directory for `.mcp.json`, or a data directory permission problem. Run from a directory where the agent config should be written.

## High memory usage

Check `KG_KUZU_BUFFER_POOL_MB` and board count. The default is intentionally conservative. Do not increase it without checking container memory.

## Agent gets permission denied

Read the required flag in the error. It may be an operation flag such as `card.validation.submit` or an `interact_in` state flag.

## `graph.lbug` missing after restart

The Docker volume was likely not mounted or `KG_BASE_DIR` changed. Restore the expected volume/path and verify storage config.

<Warning>
  Do not delete `graph.lbug` to fix KG errors. Use migration, backfill, dedup, or dead-letter reprocess.
</Warning>

## Related pages

* [MCP server configuration](/configuration/server-config)
* [Permission model](/permissions/model)
* [Dead-letter queue](/kg-operations/dead-letter)