Skip to main content

​
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:
SymptomLikely causeFix
R2Error: Access DeniedMissing/wrong R2 bindingVerify wrangler.jsonc has r2_buckets binding pointing to superbox-mcp-registry
TypeError: Cannot read properties of undefinedDurable Object class not exportedEnsure McpSession is exported as a named export in the Worker’s entry file
RangeError: Maximum call stack size exceededInfinite loop in server codeReview 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.