Troubleshooting

Use the symptom-based entries below to narrow down the cause of an APISIX problem. Each entry follows the same structure: symptoms, likely causes, checks, resolution, verification, and escalation data to collect.

Common symptom index

• 404 / route not found — [TODO] link to common-http-errors.mdx once created.
• 401 / 403 authentication errors — [TODO] link to common-http-errors.mdx once created.
• 502 / 503 / 504 upstream errors — [TODO] link to common-http-errors.mdx once created.
• etcd connection or sync failures — [TODO] link to etcd-and-config-sync.mdx once created.
• Configuration not synchronized — [TODO] link to etcd-and-config-sync.mdx once created.
• Admin API key errors — [TODO] link to common-http-errors.mdx once created.
• TLS or certificate errors — [TODO] link to tls-and-certificates.mdx once created.
• CPU or memory spikes — [TODO] link to performance.mdx once created.

Debug tools

• Use debug mode
• Set breakpoints
• Observability runbook
• Production readiness checklist