> ## Documentation Index
> Fetch the complete documentation index at: https://acm-aa28ebf6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```bash theme={null}
wrangler r2 bucket create superbox-mcp-registry
```

Then confirm `wrangler.jsonc` has:

```jsonc theme={null}
"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:

```jsonc theme={null}
"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`:

```env theme={null}
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:**

```bash theme={null}
cd backend
pip install -e .
```

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