DOCS / UWA V1 RELEASE CONTRACT SELF-HOSTED GATEWAY
Diagnostics & troubleshooting
Offline config preflight, uapctl doctor, and runtime health probes.
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
| Symptom | First checks |
|---|---|
| 401 / 403 | Client key, expiry, authorized scope (all requested scopes required upfront on /v1/datasets) |
| 503 AUTH_BACKEND_UNAVAILABLE | PostgreSQL reachability and 3s connection / 2s lookup timeouts |
| No eligible provider | Provider registration, release profile (lean_v1 vs full_experimental), operator policy, deployment use, country index, credential |
| Upstream unavailable / fallback | Vendor reachability, 95% quota gate, 25–50 km coordinate drift or 2h observation age rejection |
| Startup rejected | Run 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.