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; allow worker cycles and recheck search.
• query queue via pgm queue and confirm pending extraction is draining.

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:

• request full_response: false defaults or toggle compact modes.

Notes

• Limitations to expect:
  • personal/small-team sizing
  • OpenAI defaults (with local Ollama alternatives)
  • LLM extraction disabled by default
  • backups require gpg for encryption
• If manual import fails, use Talon dry-run first.