Ridge Troubleshooting

Diagnose from the outermost boundary inward: service, transport, session, catalog, SQL, transaction, then storage. Preserve the first structured error and SQLSTATE.

Service is unavailable

systemctl status ridged.service
pg_isready -h 127.0.0.1 -p 7898 -d ridge

Confirm the configured port, data prefix, permissions, runtime libraries, TLS files, and that the listener remains on loopback. Run ridged --check before starting a packaged binary.

Startup or TLS negotiation fails

Verify that both certificate and key are configured, readable only by the service identity, and match. Ridge password authentication is accepted only inside its configured TLS path. Check client TLS mode and avoid assuming PostgreSQL SCRAM or certificate-user mapping.

SQL is rejected

Use the structured message and SQLSTATE. Check:

An explicit unsupported response is not evidence of storage corruption.

A write disconnected

Do not replay it. The server may have committed before the response was lost. Reconnect, inspect the target by its primary or idempotency key, and decide the next action from observed state. Ridge Admin labels this outcome uncertain.

Lock or serialization conflict

SQLSTATE 55P03 indicates bounded lock contention. Transaction conflicts can also arise from expected-head or unique-key validation. Roll back the failed transaction, refresh state, and retry only when the application operation is safe and bounded.

Ridge Admin has no Local Ridge

Confirm that the current contract-3 binary is running, its profile store is writable with mode 0600, and ridged accepts connections on 127.0.0.1:7898. Restart Ridge Admin after replacing the binary; launch tokens and sessions are intentionally invalidated on restart.

Possible storage damage

Stop mutations, preserve logs and exact paths, verify available disk space, and run supported integrity/backup verification. Restore to a new target and validate it before cutover. Never repair B+Tree, WAL, catalog, index, or version files with a general file editor.