How do I install the Omni Gateway Diagnose skill?

Run npx skillmds@latest add mulesoft/omni-gateway-diagnose in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Omni Gateway Diagnose safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Omni Gateway Diagnose?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Omni Gateway Diagnose free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Omni Gateway Diagnose?

mulesoft (@mulesoft) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Omni Gateway Diagnose by mulesoft — Agent Skill

Name: Omni Gateway Diagnose
Author: mulesoft

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.

mulesoft Updated Sep 17, 2026

File contents

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

---name: omni-gateway-diagnosedescription: 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-serviceableThese 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 TeamThese 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 ChecklistCollect 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

Frequently asked questions