Troubleshooting

Use this checklist before escalating to operational logs.

What this page covers

Common failure patterns from real-world rollout and manual validation.

Core workflow

1. Service won’t start or health fails:

• check PostgreSQL startup and DATABASE_URL.
• verify docker compose logs for migration or permission errors.

2. Auth returns 401:

• confirm PGM_API_KEY matches the target key and PGM_API_URL points to current server.

3. Writes create items but search misses them:

• enrichment is asynchronous; wait for pending embedding work to clear and recheck search.
• query pgm queue, then verify the selected embedding provider is reachable from mcp-server.

4. Search conflicts on update:

• stale version values produce conflict responses; re-read entity then retry with latest version.

5. MCP transport works but output is too large:

• omit full_response, or request toon: true on list-like tools.

Notes

• Limitations to expect:
  • personal/small-team sizing
  • Compose selects OpenAI when configured with a real key, otherwise local Ollama
  • LLM extraction disabled by default
  • backups require gpg for encryption
• If manual import fails, use Talon dry-run first.