Troubleshooting

Start with the visible state instead of repeating the last action.

Symptom	Check	Action
Form is read-only	Active organization and your grant	Sign in with the intended WorkOS organization or ask an operator to correct the grant
Publish action is absent	Role and active organization	A customer needs publisher; shared catalogue publication requires an operator
Publish is blocked	Ready to publish? on the saved form	Open the named tab and correct each listed field
Publication remains pending	Worker health and backlog	Restore the worker; do not publish another revision
Publication is failed	Sanitized error and last delivered revision	Correct the cause, then use Retry now as an operator
CTX source is unavailable	Adapter availability, live columns, grants, and sync notes	Repair the FDW/provider, run Sync from CTX, then use the bounded query check
Ingestion returns 404	Signed-in account, object identity, and published state	Use the same customer account and GID as the accepted publication
Ingestion returns 422	Stored mode, declared keys, value types, batch and time bounds	Correct the fields reported in the error response
Query returns 404	Token grants and access class	Inaccessible services are deliberately not disclosed
Save reports a version conflict	Another user saved the draft	Review the reloaded version and reapply your intended change

Use /healthz to check the process and /readyz to check PostgreSQL connectivity. Neither proves ClickHouse, CTX FDW, or an upstream provider is healthy. Run one bounded query for the affected service and check the admin source-health and publication views.

If the problem is local Docker state, follow Run locally. For API errors, open the API reference with the same token and inspect code, fields, and requestId in the documented response. Keep requestId when escalating the failure.