Troubleshooting

Real error strings you'll see in your terminal, with the exact command that fixes each. If you hit something not listed here, please open an issue.

Install

zsh: command not found: pip

You don't have pip on your PATH (common on a fresh macOS — Python may be installed but pip ≠ pip3 ≠ available in the shell). Don't install pip globally — use uv instead:

# install uv once
curl -LsSf https://astral.sh/uv/install.sh | sh

# install pyfastcms as a CLI tool (auto-isolated, no venv needed)
uv tool install pyfastcms

error: externally-managed-environment when running pip

Your system Python is locked down (PEP 668 — common on recent Debian/Ubuntu/macOS). Either:

uv tool install pyfastcms          # recommended — bypasses the issue cleanly
# or
python -m venv .venv && source .venv/bin/activate && pip install pyfastcms

fastcms: command not found after install

The CLI entry-point isn't on your PATH. If you installed with uv tool install, run uv tool update-shell to ensure ~/.local/bin is on your PATH, then open a new terminal. If you installed with pip install, make sure you're inside the same venv where you ran pip.

Boot

/admin/* returns 500 with cannot use 'tuple' as a dict key

You're on an old pyfastcms (0.1.3 / 0.1.4) with a Starlette ≥1.0 environment. Upgrade:

uv tool upgrade pyfastcms       # if installed via uv tool
# or
pip install --upgrade pyfastcms

Then restart fastcms dev. Fixed in 0.1.5.

SECRET_KEY validation error at startup

You're missing the required secret. Set it in .env or via environment:

echo "SECRET_KEY=$(openssl rand -hex 32)" >> .env

Server starts but /health is the only reachable endpoint

You're hitting it before the lifespan finished. Wait ~2 seconds for the first cold boot (DB init + plugin discovery), then retry. If it persists after 30 seconds, check data/test_verify.db-* lock files aren't from a prior crashed run — delete them and restart.

port 8000 already in use

Another process is listening. Either kill it:

lsof -i :8000               # find the PID
kill <PID>

Or run on a different port:

fastcms dev --port 8765

Plugins

Plugin sidebar entry doesn't link anywhere

You're on plugin code older than 2026-05-11 where add_admin_page pointed at /admin/plugins/<id> — a URL with no handler. Update the plugin:

fastcms plugin install <plugin-name> --force

Then restart fastcms dev. Fixed in fastcms-plugins after 2026-05-11.

Webhooks never fire

Three things to check, in order:

1. Plugin loaded? — visit /admin/plugins. If your hooks come from a custom plugin, make sure it's listed.
2. Server restarted after installing the plugin? — plugins only register at boot. Ctrl+C, then fastcms dev again.
3. Webhook subscribed to the right events? — webhook events field must contain "create", "update", or "delete" (short form, not record.created).

Fixed multiple webhook bugs in 0.1.5 — make sure you're on it.

/admin/plugins/<id>/settings returns {}

That's a JSON endpoint and the empty body is correct — no settings have been saved yet. Once you configure the plugin (e.g., POST /api/v1/plugins/ai/configure), the response will populate.

If you wanted a UI page, that's /admin/<plugin's-registered-url> — visit the plugin's row at /admin/plugins and click Open if it has an admin UI.

fastcms plugin install fails with Permission denied

You're running it outside a writable project directory. Run it from inside the folder created by fastcms init, where there's a plugins/ subdirectory the CLI can write to.

AI plugins specifically

ollama: command not found

Install Ollama (only needed if you want local LLM, no API key path):

brew install ollama                          # macOS
# or one-line installer for Linux:
curl -fsSL https://ollama.com/install.sh | sh

ollama serve &                               # start the daemon
ollama pull llama3.1:8b nomic-embed-text     # pull models

RAG returns "I couldn't find any relevant information" for queries that should match

The retrieved chunks scored below the 0.1 cosine-similarity threshold. Two paths to fix:

1. Real embeddings provider — make sure you've configured ai-core with a real provider (OpenAI / Anthropic / Ollama), not a placeholder. Fake / hash-based embeddings produce noisy similarity scores.
2. Re-ingest with smaller chunks — try chunk_size: 300 instead of the default 500 if your documents are short paragraphs.

Webhook signature mismatch on the receiving side

The webhook payload is signed over the exact bytes sent on the wire. If you re-serialize the JSON before computing HMAC, separators won't match. Use the raw request.body(), not json.dumps(parsed). The fixed example is in the Webhooks docs.

Deployment

Docker build fails with pip: command not found in builder stage

You're on an old Dockerfile (pre-0.1.4) that uses plain pip. Upgrade:

git pull origin main      # in the fastCMS repo
docker compose build      # rebuilds with the uv-based Dockerfile

git push returns 403 Permission denied

You have multiple GitHub identities. Switch to the one with write access:

gh auth switch
gh auth setup-git
git push

If macOS Keychain has a stale entry, nuke it:

printf "protocol=https\nhost=github.com\n\n" | git credential-osxkeychain erase

Webhook events don't reach connected WebSocket clients across multiple replicas

You're scaled out without Redis. Enable Redis pub/sub:

# add to .env
REDIS_ENABLED=true
REDIS_URL=redis://redis:6379/0

# add to docker-compose.yml
#   redis:
#     image: redis:7-alpine

See the Docker deployment guide for the full multi-replica setup.

Reporting bugs

Hit something not listed here? Open a GitHub issue with:

1. Your install method (uv tool install / pip install / Docker / source)
2. Your Python version (python --version)
3. pyfastcms --version
4. The error string verbatim
5. What you were trying to do