> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Resolve common issues with Blaxel deployments including build failures, runtime errors, connectivity problems, and CLI authentication.
This page describes common issues and how to troubleshoot them. If your issue is not covered below, you can also [check our knowledge base](https://support.blaxel.ai).
For current service status, refer to [https://status.blaxel.ai/](https://status.blaxel.ai/)
## Preview URLs return a `502 Bad Gateway` server error
This error occurs when the application server is either not running inside the sandbox, or is running but binding to `localhost`. In the latter case, it is only reachable inside the sandbox and the external preview URL will not be able to access it.
To resolve this error, first confirm that the application server is running. If it is, then ensure that it is configured to bind to IP address `0.0.0.0`, so that it listens on all available network interfaces. Once this is done, restart the application server. To avoid IPv4/IPv6 compatibility issues, we recommend using the environment variable `HOST` instead of setting the address to a static value.
For example, in code:
```tsx TypeScript theme={null}
const host = process.env.HOST || '0.0.0.0';
app.listen(3000, host, () => {
console.log(`Server is running`);
});
```
```python Python theme={null}
host = os.environ.get("HOST", "0.0.0.0")
app.run(host=host, port=3000)
```
or at the command line:
```tsx TypeScript theme={null}
npm run dev -- --host 0.0.0.0
# or
npm serve -- --host 0.0.0.0
```
```python Python theme={null}
python main.py --host 0.0.0.0
```
## Sandbox commands return a `502 Bad Gateway` server error
This error occurs for three possible reasons:
1. The sandbox API is called too soon after sandbox creation. The solution is to retry the request.
2. The sandbox API was unexpectedly terminated - for example, if the sandbox runs out of memory. The solution is to delete and recreate the sandbox, which also restarts the sandbox API.
3. The sandbox never started so the deployment status is set to `ERROR`. The solution is to recreate the sandbox.
The sandbox logs will typically contain additional information to identify the root cause of this error. Sandbox logs can be viewed in the [Blaxel Console](https://app.blaxel.ai) or with the Blaxel CLI using the command `bl logs sandbox SANDBOX-NAME`.
Deleting and recreating will cause the current state of the sandbox to be lost.
## Sandbox deployment fails with `STARTUP TCP probe failed` or `DEADLINE_EXCEEDED` error
This error occurs when the server running inside the sandbox is not binding to the correct host and port.
To resolve this error, configure your server to bind to the host and port designated by the `HOST` and `PORT` environment variables. Blaxel automatically injects these variables during deployment.
For example:
```tsx TypeScript theme={null}
const port = parseInt(env.PORT || "80");
const host = process.env.HOST || "0.0.0.0";
app.listen(port, host, () => {
console.log(`Server is running`);
});
```
```python Python theme={null}
port = os.environ.get("PORT", "80")
host = os.environ.get("HOST", "0.0.0.0")
app.run(host=host, port=port)
```
## Sandbox deployment fails with a `QUOTA_EXCEEDED` error or a 400 status code.
This error indicates that the maximum memory limit for the account has been reached in the current tier.
Blaxel has a tiering system that unlocks higher limits and features on the platform as your tier progresses. To resolve this error, upgrade your account to a higher tier, which unlocks higher RAM limits for sandboxes.
To see more details on which quota was exceeded or to upgrade to a higher tier, visit the [**Quotas** page of the Blaxel Console](https://app.blaxel.ai/account/quotas).
## Models return a 429 error
This error occurs when a model reaches its maximum token limit.
To resolve this error, adjust the model's token usage policy. Token usage policies control the maximum number of tokens your model APIs can handle within a specific time period. You can configure the maximum number of input tokens, output tokens and/or total tokens using these policies.
## Sandbox commands return an `ENOSPC: no space left on device` error
This error occurs when your sandbox runs out of storage space. This usually happens when your file storage requirements exceed the available memory since, for performance reasons, Blaxel sandboxes reserve, when possible, [approximately 50% of their available memory](/Sandboxes/Overview#memory-and-filesystem) for the filesystem.
To resolve this error, you have two options:
* Increase the available memory allocation for the sandbox, which also increases the available filesystem storage.
Increasing memory also increases CPU allocation
* 8GB memory = 4 CPU cores
* 16GB memory = 6 CPU cores
* Add storage using [volumes](/Sandboxes/Volumes). Adding storage requires deleting and recreating the sandbox first.
Volumes are slower than the in-memory filesystem.
## Sandbox commands return a `404 WORKSPACE_NOT_FOUND` error
This error occurs when a [workspace is not provisioned correctly](/troubleshooting/error-codes).
To resolve this error, please contact us for support via [Discord](https://discord.gg/G3NqzUPcHP) or [online contact form](https://blaxel.ai/contact).
## Volume creation fails with a 403 error
This error could occur when:
* volumes are not enabled for the workspace;
* volume size exceeds the maximum allowed size;
* total volume size exceeds maximum allowed total size.
To resolve this error, you can:
* Enable volumes (if not enabled)
* Reduce the size of your volumes.
* Contact us to increase your volume size limits.
## Connections to the sandbox terminal fail with `websocket: bad handshake`
This error could occur when:
* you are using an outdated CLI version
* you are using a custom sandbox image without the sandbox API
* you are using a deprecated image
To resolve this error, you can:
* upgrade to the latest CLI version
* if using a pre-built image, ensure that you are using a [current version of the image](/Sandboxes/Templates#pre-built-templates). If using an older image, recreate the sandbox with the latest version.
* if using a custom Docker image, ensure that you include the sandbox API. If it's missing, add it to your image build process and recreate the sandbox with the new image.
## Hot reloads fail on Webpack previews
This error occurs when a Webpack server is configured to use the same port as local development, but the sandbox preview URL is mapped to a different port. As a result, when hot reloading previews, your client is trying to connect to the local development port instead of the sandbox's preview URL port.
To resolve this error, add a conditional in the `webSocketURL` of your `webpack/config.dev.js` to handle the different ports:
```javascript highlight={9-13} theme={null}
///... rest of webpack/config.dev.js
module.exports = {
devServer: {
host: "::",
port: 3000,
allowedHosts: [".bl.run", ".beamlit.net", "localhost", "127.0.0.1"],
client: {
webSocketURL: {
port: process.env.BL_CLOUD === "true" ? 443 : 3000,
},
},
headers: {
...
},
},
/// ... rest of webpack/config.dev.js
```
## A deleted agent or MCP server still appears in the Blaxel Console listing
This error occurs when a deletion operation didn't fully complete, leaving the resource in a stuck "deleted" state.
To resolve this, run the `bl delete` command again on the same resource:
```bash theme={null}
bl delete agent
# or
bl delete function
```