| name | omni-gateway-diagnose |
| description | Diagnose Omni Gateway errors and failures given any combination of log output,
dump files, or symptom descriptions. Use when the user reports a gateway error
(5xx, 4xx, gateway unreachable, policy not applying), has log output to
analyze, needs to decide whether to request debug logs from a customer, or
needs to determine whether an issue requires escalation to the gateway team.
|
Diagnose Gateway Error
Triage by Symptom
| Symptom | First Check | Invoke Skill |
|---|
| 5xx errors on all requests | Upstream connectivity, spec.address binding | omni-gateway-config |
| 4xx errors (auth/policy) | PolicyBinding targeting, policy config | omni-gateway-config |
| Gateway unreachable / port not responding | Listen address (0.0.0.0 vs localhost), port conflicts | omni-gateway-config |
| Policy not applying | PolicyBinding → ApiInstance cross-reference | omni-gateway-config |
upstream connect error / connection refused | Upstream service health, routes config | omni-gateway-logs |
| TLS handshake failures | Certificate validity, TLS config in conf.d | omni-gateway-logs |
xDS disconnected / control plane errors | Anypoint connectivity, registration token validity | omni-gateway-logs |
| STARTED state never reached | Registration artifact, conf.d correctness | omni-gateway-install (re-register), then omni-gateway-config |
| Known-good config still failing | Live deployed state may differ from conf.d | omni-gateway-dump |
By Available Artifact
- Logs provided → invoke
omni-gateway-logs
- conf.d directory available → invoke
omni-gateway-config
- Dump file provided → invoke
omni-gateway-dump
- Symptom description only → ask the user which artifacts are available before proceeding
Escalation Decision
Self-serviceable
These issues can be resolved without escalating to the gateway team:
- Misconfigured
PolicyBinding (wrong targetRef, missing ApiInstance)
- Wrong
spec.address (using localhost instead of 0.0.0.0)
- Upstream service unreachable (network/firewall issue outside the gateway)
- Expired or revoked Anypoint registration token
Escalate to Gateway Team
These issues require gateway team involvement:
- Repeated xDS sync failure after verifying a valid configuration
- Envoy process crash (crash loop, OOMKill)
STARTED state never reached after valid registration and correct conf.d- Issue is reproducible after configuration is confirmed valid by
omni-gateway-config
Escalation Package Checklist
Collect all of the following before opening a support ticket:
Related Jobs
omni-gateway-logs — parse log output to surface errors and anomaliesomni-gateway-config — structural and cross-reference validation of conf.d filesomni-gateway-dump — interpret a diagnostic dump ZIP for live gateway state
