---
title: Troubleshooting
description: 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
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
  ~/.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.
