Skip to main content
This page describes common issues and how to troubleshoot them.

​
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: 
const host = process.env.HOST || '0.0.0.0';
app.listen(3000, host, () => {
  console.log(`Server is running`);
});
or at the command line: 
npm run dev -- --host 0.0.0.0
# or
npm serve -- --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 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: 
const port = parseInt(env.PORT || "80");
const host = process.env.HOST || "0.0.0.0";
app.listen(port, host, () => {
  console.log(`Server is running`);
});

​
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.

​
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 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 = 8 CPU cores
  • Add storage using 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. To resolve this error, please contact us for support via Discord or online contact form.

​
Volume creation fails with an error

This error occurs when a volume is smaller than the template data, or when the workspace quota limit is breached. To resolve this error, you can:
  • Provision extra space for your volume beyond the template content size. We recommend provisioning at least 20-30% extra space.
  • Contact us to increase your workspace quota limit.

​
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: 
///... 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