Debugging Upstream Failures

Use this guide when proxied routes fail and you need to isolate routing, auth, and upstream behavior. Start by checking whether the gateway matched the right

Use this guide when proxied routes fail and you need to isolate routing, auth, and upstream behavior. Start by checking whether the gateway matched the right route, then whether auth passed, then whether the upstream responded. This page provides a step-by-step process for narrowing down the failure layer.

Last reviewed: 2026-03-06

When to use this

Use the deployment and troubleshooting guides when you are deploying the gateway to Cloudflare, setting up CI/CD, running tests, or diagnosing production issues. These guides cover the operational side of the gateway lifecycle from local development to production debugging.

Key concepts

• The gateway deploys as a standard Cloudflare Worker using wrangler deploy. The wrangler.toml file defines the worker name, entrypoint, compatibility settings, and binding declarations.

• GitHub Actions can automate deployments, running config validation, tests, and docs checks before publishing the worker. The workflow uses the same wrangler deploy command.

• The gateway repo includes Vitest unit tests and optional E2E tests using unstable_dev. Run unit tests with npm test and E2E tests with the RUN_LOCAL_WORKER_E2E=true flag.

• When debugging upstream failures, isolate whether the issue is in routing (wrong path matched), auth (token rejected), or the upstream itself (backend error). Check wrangler tail logs for the gateway's perspective.

Repo-grounded example

{
  "servers": [
    { "alias": "upstream", "url": "https://api.example.com/base" }
  ],
  "paths": [
    {
      "method": "GET",
      "path": "/proxy/{.+}",
      "integration": {
        "type": "http_proxy",
        "server": "upstream"
      }
    }
  ]
}

This snippet defines an HTTP proxy route. When this route fails, check the gateway logs (wrangler tail) to see if the request matched this path, whether auth was evaluated, and what response the upstream returned. The logs show each step in the request lifecycle.

Troubleshooting

• If wrangler deploy fails with "missing binding", check your wrangler.toml for typos in binding names and verify that all referenced KV namespaces, service bindings, and secrets exist in your Cloudflare account.

• If GitHub Actions deploys succeed but the worker returns 500, check whether environment variables and secrets are set in the Cloudflare dashboard -- they are not deployed by Wrangler and must be configured separately.

• If E2E tests fail with "unstable_dev not found", make sure you are running a Wrangler version that supports unstable_dev and that RUN_LOCAL_WORKER_E2E=true is set in your environment.

• If routes work locally but not in production, compare the config source: local dev uses the file system, while production may use KV or SAG_API_CONFIG_JSON. Confirm the production config matches your local config.

Related docs

• wrangler

• github actions

• gateway troubleshooting matrix