Troubleshooting

Diagnose and fix common SuperBox deployment issues

Deployment issues

wrangler deploy fails with authentication error

Error: Not authenticated. Please run `wrangler login`.

Fix: Run wrangler login and complete the browser OAuth flow. Your session token is stored in ~/.wrangler/config/default.toml.

---

Worker deploys but requests return 500

Check live logs:

wrangler tail superbox-executor --format pretty --status error

Common causes:

Symptom	Likely cause	Fix
R2Error: Access Denied	Missing/wrong R2 binding	Verify wrangler.jsonc has r2_buckets binding pointing to superbox-mcp-registry
TypeError: Cannot read properties of undefined	Durable Object class not exported	Ensure McpSession is exported as a named export in the Worker’s entry file
RangeError: Maximum call stack size exceeded	Infinite loop in server code	Review the published server’s entrypoint

---

Bundle too large

Error: Script startup exceeded CPU time limit.

or

Error: Worker size limit exceeded (10 MB compressed).

Fix:

1. Run npx wrangler deploy --dry-run --outdir dist to inspect what’s in the bundle
2. Move large static assets out of the Worker and into R2
3. Tree-shake unused imports

---

R2 bucket not found

NoSuchBucket: The specified bucket does not exist

Fix: Create the bucket and verify the binding name matches:

wrangler r2 bucket create superbox-mcp-registry

Then confirm wrangler.jsonc has:

"r2_buckets": [
  { "binding": "REGISTRY", "bucket_name": "superbox-mcp-registry" }
]

---

Durable Object errors

Durable Object 'McpSession' is not exported by the entrypoint worker script

Fix: Ensure wrangler.jsonc declares the DO class with the correct class name:

"durable_objects": {
  "bindings": [
 { "name": "MCP_SESSION", "class_name": "McpSession" }
  ]
}

And that McpSession is a named export in src/index.ts.

---

Runtime issues

401 Unauthorized on every request

The Firebase JWT is missing, expired, or belongs to the wrong project.

Fix:

1. Verify FIREBASE_PROJECT_ID in the backend .env matches your Firebase project
2. Confirm the AI client is sending the token in Authorization: Bearer <token>
3. Check token expiry - Firebase JWTs expire after 1 hour

---

Session not found after reconnect

AI client receives 404 on a resumed session.

This is expected - DO sessions evict after 30 minutes of inactivity. The client should start a new session by omitting the Mcp-Session-Id header (or using a new UUID).

---

Server not found in R2

404: server 'my-server' not found in registry

Fix:

1. Run superbox push again to republish the server metadata
2. Verify the object key in R2: wrangler r2 object get superbox-mcp-registry my-server.json
3. Check Back end logs for R2 write errors during push

---

Backend API issues

Go API crashes on startup

failed to connect: CLOUDFLARE_R2_ENDPOINT is not set

Fix: Ensure all required environment variables are set in .env:

CLOUDFLARE_R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
CLOUDFLARE_R2_ACCESS_KEY_ID=...
CLOUDFLARE_R2_SECRET_ACCESS_KEY=...
CLOUDFLARE_R2_BUCKET_NAME=superbox-mcp-registry
FIREBASE_PROJECT_ID=...

---

security_helper.py or s3_helper.py not found

The Go API invokes these as subprocess commands. They must be on the PATH or in the working directory.

Fix:

cd backend
pip install -e .

This installs the superbox package in editable mode, making both helpers available as module scripts.