# Polygres Troubleshooting

> Diagnose Polygres MCP, OAuth connections, CLI, Runtime API, projects, jobs, synchronization, migrations, and retrieval through public read-only evidence. Use for scope or project-boundary issues, timeouts, partial failures, readiness, Context operations, graph, vector, text, hybrid, and Joint retrieval.

- Skill: `evokoa/polygres-troubleshooting` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add evokoa/polygres-troubleshooting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/evokoa/polygres-troubleshooting/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: evokoa (https://skillmd.com/u/evokoa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/evokoa/polygres-troubleshooting

---


# Polygres Troubleshooting

Use read-only checks first. Resolve context, preserve evidence, classify the
failure boundary, and recommend the smallest safe correction. Do not mutate
while diagnosing.

When Polygres MCP tools are available, read
`references/mcp-tool-contract.md`, call `whoami`, and use the discovered read
catalog before CLI or SDK fallback. Treat the connection URL restrictions,
OAuth installation, current scopes, project boundary, project mode, and catalog
version as separate diagnostic layers.

## Workflow

1. Read the installed `polygres --help` and command-specific help before using
   a command. Installed behavior is the source of truth for CLI compatibility.
2. Resolve identity, configuration source, and one exact project using
   `references/context-and-connectivity.md`. Stop on an ambiguous project.
3. Capture the symptom, timestamp, sanitized command or SDK call, exit code or
   exception type, `request_id`, job ID, and whether pagination returned a
   cursor.
   For generated pipelines, also capture the manifest state, plan digest,
   approved action IDs, checkpoint, and last successfully completed stage.
4. Inspect project and database evidence with
   `references/projects-and-database.md`.
5. If `project_mode` is `synced`, use `references/synced-projects.md` and skip
   target database, row, import, and migration checks.
6. For import job or migration failures, use
   `references/jobs-and-migrations.md`. For graph, vector, text, hybrid, or
   general readiness failures, use `references/retrieval.md`. For pgContext
   capability, collection, point, operation, recall, or Joint failures, use
   `references/context.md`.
   Use `references/mcp-retrieval-quality.md` for retrieval evaluation through
   MCP and `references/mcp-operation-recovery.md` for MCP operation state.
7. Classify the fault as CLI/local configuration, control-plane, Runtime API,
   Postgres/database or pooler, or asynchronous job state. Use
   `references/errors-and-escalation.md` for typed SDK errors and escalation.
8. Re-check status before retry. Recommend a corrective action, but obtain
   explicit approval and delegate supported mutations to `$polygres-cli` or
   application changes to `$polygres-sdk`.

For a single-row write that lost the response after submission, treat the
commit outcome as ambiguous unless public evidence resolves it. Do not
automatically retry a row-only insert, upsert, or ignore. For a Context-backed
write, replay the exact request with its exact idempotency key within the
24-hour replay window; the composite ledger prevents another row mutation.
After `ROW_CONTEXT_IDEMPOTENCY_EXPIRED`, inspect the row and Context point before
choosing a new key.

## Evidence rules

- Use only commands confirmed by installed help and public `$polygres-sdk`
  methods. Never guess a private endpoint or use internal observability.
- Preserve request and job IDs exactly. Distinguish absent evidence from a
  successful check.
- Never log a database password, API key, authorization header, connection
  string containing credentials, or full environment output.
- Do not retry validation, authentication, permission, or compatibility errors
  as if they were transient. Bound any retry for a rate limit or timeout.
- Do not request approval again for a corrective action already covered by an
  unchanged consolidated pipeline review. Ask again when its project, source
  scope, action set, egress, destructive effect, or plan digest changed.
- Report pagination and partial failure explicitly; a successful first page or
  one healthy subsystem does not prove the whole operation succeeded.

## Diagnostic report

- **Resolved identity:** account identity or the exact reason it is unknown.
- **Resolved project:** exact project ID or the ambiguity that blocked selection.
- **Symptom:** observable failure and affected operation.
- **Observed evidence:** sanitized statuses, exception classes, and timestamps.
- **Likely cause:** evidence-backed classification with confidence.
- **Safe checks performed:** public read-only commands and SDK calls used.
- **Corrective action:** smallest documented action, not yet performed.
- **Approval or escalation:** approval needed or escalation destination.
- **IDs retained:** request IDs, job IDs, and cursors without secrets.
- **Unknowns:** missing, stale, incompatible, or contradictory evidence.

## Boundaries

- Do not mutate while diagnosing, rotate credentials, retry jobs or Context
  operations, apply migrations, reconcile points, rebuild graph resources, or
  start a text, vector, or Context reindex.
- Do not call an undocumented or private route and do not query a private
  observability system.
- Do not claim root cause when evidence supports only a likely boundary.