Skip to main content

/gws-debug

Diagnose a failing GWS service. Type /gws-debug inside your AI agent and it will work through a mechanical 8-step runbook from automated signals to targeted inspection to fix.

When to use it​

  • A service is crashing (CrashLoopBackOff, ImagePullBackOff, etc.)
  • A pod is Running but the URL doesn't respond
  • File-sync is stuck (Halted*)
  • /gws-status flagged something as partial or down
  • Restart count is climbing and you want to know why

The runbook​

  1. Programmatic diagnosis — gws doctor --json [--service <svc>]. Each finding has a fix field with the exact remediation. Unambiguous fixes (USER directive, distroless base, port mismatch, localhost bind) are applied directly to .gws/services/<svc>/ artifacts and gws rebuild <svc> is run.
  2. Pod-level signals — gws status --json to identify which service to drill into.
  3. Container logs — gws logs <svc> and gws logs -f <svc>, matched against a catalog of known error signatures (EADDRINUSE, ECONNREFUSED, missing module, etc.).
  4. Exec into the pod — gws exec <svc> to inspect the running process, env vars, mounted secrets, and filesystem.
  5. File-sync session state — checks the SSH sidecar and rsync state; reset with gws down -y && gws up -y if halted.
  6. URL probe — curl the gateway-routed URL; mismatches between gws.json port, container EXPOSE, and probe ports are flagged.
  7. Apply fix — edits the relevant .gws/services/<svc>/Dockerfile or k8s/deployment.yaml, then runs gws rebuild <svc>.
  8. Escalate — if the fix attempt count exceeds the cap, the skill stops and surfaces the diagnosis with everything it learned, so you can take over.

When to invoke directly vs. let /gws-up chain into it​

  • /gws-up will hand off to /gws-debug automatically if its post-deploy verification fails.
  • Invoke /gws-debug directly when the environment is already up but a service has gone unhealthy mid-session, or when /gws-status flags something.

See also​