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.
How do I install this agent skill?
npx skills add https://github.com/mulesoft/mulesoft-dx --skill omni-gateway-diagnoseIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides diagnostic guidance for troubleshooting the Omni Gateway. It contains triage logic and checklists but no executable code, network connections, or sensitive data access. No security issues were detected.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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(wrongtargetRef, missing ApiInstance) - Wrong
spec.address(usinglocalhostinstead of0.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)
STARTEDstate 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-logsfor how to enable) - Diagnostic dump file (see
omni-gateway-dumpfor analysis before escalating) -
conf.d/listing with secrets omitted (file names + kind/name inventory only) -
flexctl versionoutput - 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 anomaliesomni-gateway-config— structural and cross-reference validation of conf.d filesomni-gateway-dump— interpret a diagnostic dump ZIP for live gateway state
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/mulesoft/mulesoft-dx/omni-gateway-diagnose">View omni-gateway-diagnose on skillZs</a>