# Omni Gateway Diagnose

> 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.

- Skill: `mulesoft/omni-gateway-diagnose` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add mulesoft/omni-gateway-diagnose`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mulesoft/omni-gateway-diagnose/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mulesoft (https://skillmd.com/u/mulesoft)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mulesoft/omni-gateway-diagnose

---


# 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:

- [ ] Full gateway logs at debug level (see `omni-gateway-logs` for how to enable)
- [ ] Diagnostic dump file (see `omni-gateway-dump` for analysis before escalating)
- [ ] `conf.d/` listing with secrets omitted (file names + kind/name inventory only)
- [ ] `flexctl version` output
- [ ] Platform: Linux / Docker / Kubernetes / CloudHub
- [ ] Reproducible steps or a timeline of when the failure started

## Related Jobs

- `omni-gateway-logs` — parse log output to surface errors and anomalies
- `omni-gateway-config` — structural and cross-reference validation of conf.d files
- `omni-gateway-dump` — interpret a diagnostic dump ZIP for live gateway state