Troubleshooting

Read MAQPNA's error messages, find the cause of common failures from a symptom table, and collect diagnostics with doctor, status and support-bundle.

Every maqpna error has the same shape, so you can read it the same way every time. This page explains that shape, lists the common errors by symptom, and shows the three diagnostic commands: maqpna doctor, maqpna status and maqpna support-bundle.

flowchart TD
  A[Something fails] --> B{Read the error:<br/>what, why, next command}
  B -->|local MAQPNA| C[maqpna dev status<br/>.maqpna/logs/]
  B -->|cluster| D[maqpna status]
  D --> E[maqpna doctor -o json]
  E --> F[GET /readyz problems]
  F --> G[Fix, or maqpna support-bundle<br/>for support]

How to read an error#

Errors go to stderr in three parts:

✗ <what happened>
  <why, or what to check>
  → <the next command to run>

The first line is the error itself, so scripts that match on it keep working. Warnings use ! in the same shape. Usage errors also print the command's synopsis. For example:

$ maqpna stauts
✗ unknown command "stauts"
  Did you mean status?
  → maqpna help

On a terminal without UTF-8 (or with MAQPNA_ASCII=1), the symbols are x, !, * and the arrow is ->.

Exit status#

Symptom, cause and fix#

The hints in this table are the CLI's own: the CLI recognises these failures without any per-command code.

Local MAQPNA (maqpna dev)#

maqpna dev status shows each process and whether the gateway is ready:

$ maqpna dev status
maqpna-gateway   pid 76424   running
maqpna-identity  pid 76328   running
mcp-echo         pid 76326   running
stub-llm         pid 76327   running
gateway http://127.0.0.1:8080 ready=true

Gateway /readyz#

A gateway that is not ready leaves the Service and returns 503 with a list of problems:

kubectl -n maqpna-system port-forward svc/maqpna-gateway 8080 &
curl -s localhost:8080/readyz

The response has this form:

{"status": "not ready", "problems": ["state backend unreachable: …"]}

A healthy gateway answers {"status":"ready"}.

maqpna status#

One screen: the Helm release and its revisions, workloads, sessions by phase, pending approvals, active revocations, the audit ledger head and its verify state, tainted sessions, and the licence state with billable nodes this month.

maqpna status -n maqpna-system
maqpna status -o json

maqpna doctor#

doctor checks health and security posture: the gateway's posture checks (GET /v1/posture, auditor or admin role), /readyz, and the cluster checks (CRDs, RuntimeClasses per trust tier, NetworkPolicy, attestation, licence). It exits 3 when a check fails, and on warnings with --strict.

maqpna doctor                                   # everything
maqpna doctor --component gateway --strict      # one area
maqpna doctor --component audit,state -o json
maqpna doctor --accept attest-verifier          # report a known risk as accepted for this run

--component takes all, gateway, cluster, or components: gateway, audit, state, identity, attest, operator, sandbox, network, license.

Before you deploy a configuration, check it offline:

maqpna doctor --offline --config gateway.json [--sovereignty sovereignty.json]

The offline output and every check are on Security hardening.

maqpna support-bundle#

maqpna support-bundle --since 2h --agent-namespaces --out bundle.tar.gz

It writes a redacted archive with versions, the doctor report, the Helm release history, MAQPNA objects, events and component logs (--tail lines per container, default 2,000). With --gateway and a token, it adds the gateway posture.

What is never collected or always redacted:

• Secret values: only Secret names and key names are collected.
• In logs, values, ConfigMaps and custom resources: bearer and basic credentials, JWTs, passwords in URLs and DSNs, PEM private keys, values of keys named like token, secret, password, dsn, hmac or apiKey, and cloud API keys.
• Agent logs: --agent-namespaces adds pod lists and events of agent namespaces, not their logs.
• The audit ledger itself.

Review the archive before you send it.

Next steps#

• Monitoring and alerts: alerts and runbooks.
• FAQ
• Command reference: maqpna doctor, maqpna status, maqpna support-bundle.