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

# Troubleshooting

> The first places to look when setup, auth, plugin wiring, or docs-driven flows go wrong.

If something feels broken, this page tells you where to look first.

## What this means in practice

Common problems include:

* bad or missing API keys
* wrong backend or MCP URL
* Docker or port conflicts in local Docker Convex mode
* stale OpenClaw plugin installs
* local environment files missing
* public docs repo / mirror / Mintlify mismatch

## How it actually works

The best operational troubleshooting sources are:

* `scripts/crystal-doctor.sh`
* `README.md`
* `mcp-server/README.md`
* `packages/mcp-server/README.md`

## Commands / examples

```bash theme={"system"}
openclaw plugins info crystal-memory
openclaw crystal_status
openclaw crystal_doctor
npm run crystal:doctor
npm run test:smoke
```

`openclaw plugins info crystal-memory` confirms that OpenClaw can see and load the installed plugin. `openclaw crystal_status` and `openclaw crystal_doctor` are available after an install-script OpenClaw install. The `npm run ...` commands require running from a Memory Crystal source checkout.

## Common mistakes

* assuming every failure is a code bug instead of an environment issue
* skipping the doctor script and debugging blind
* forgetting that Mintlify/public-repo issues are deployment-source issues, not plugin/runtime issues

## Source of truth

Primary files behind this page:

* `scripts/crystal-doctor.sh`
* `README.md`
* `.env.example`
* `mcp-server/README.md`
* `packages/mcp-server/README.md`

## Local-first checks

When local-first mode fails, check these before reinstalling:

* Docker is installed and the daemon is running.
* Ports `3210`, `3211`, and `6791` are free on `127.0.0.1`.
* The installed backend artifact under `~/.memorycrystal/local-backend/<version>` has a passing doctor command:

  ```bash theme={"system"}
  ~/.memorycrystal/local-backend/<version>/bin/doctor
  ```
* The client config points to the local endpoint only for clients you accepted during install.
* Hosted Memory Crystal auth/license validation still succeeds before local credential provisioning.

If a config mutation failed, restore the backup path printed by the installer and re-run the installer in cloud or local mode.