Documentation
DocumentationDiagnostics & troubleshooting
DOCS / UWA V1 RELEASE CONTRACT SELF-HOSTED GATEWAY

Diagnostics & troubleshooting

Offline config preflight, uapctl doctor, and runtime health probes.

ONE GATEWAYCoordinates → eligible provider → canonical responseWhy UWA
On this page 3 sections

#Offline preflight and doctor checks

go run ./cmd/gateway --check-config
go run ./cmd/uapctl doctor --json
curl -i http://127.0.0.1:8080/health
curl -i http://127.0.0.1:8080/readiness
curl -i http://127.0.0.1:8080/liveness

/health, /readiness and /liveness bypass client rate limiting. When APP_METRICS_MODE=loopback is enabled on 127.0.0.1, scrape Prometheus metrics with curl -H "Authorization: Bearer $APP_METRICS_TOKEN" http://127.0.0.1:8080/metrics.

#Failure matrix

SymptomFirst checks
401 / 403Client key, expiry, authorized scope (all requested scopes required upfront on /v1/datasets)
503 AUTH_BACKEND_UNAVAILABLEPostgreSQL reachability and 3s connection / 2s lookup timeouts
No eligible providerProvider registration, release profile (lean_v1 vs full_experimental), operator policy, deployment use, country index, credential
Upstream unavailable / fallbackVendor reachability, 95% quota gate, 25–50 km coordinate drift or 2h observation age rejection
Startup rejectedRun gateway --check-config and uapctl doctor --json; check Redis and APP_PROVIDER_QUOTAS_JSON

#Evidence before shipping

Record verification outcomes for real PostgreSQL 16 migrations, Redis 7 atomic Lua quotas, Windows SCM / Linux systemd lifecycle, permitted live upstream calls, and provider attribution before declaring production certification.

Canonical contracts: docs/openapi.yaml (lean_v1) and docs/openapi.experimental.yaml · Verify against your build before production use.

Search local documentation. No external requests.

↑↓ to move · Enter to openESC to close