Troubleshooting

Solutions to the most common issues when integrating with Mudbase Cells.

Exec appears to cut off at 30 seconds

Symptom: Any command that takes longer than 30 seconds returns an empty response or a truncated stream, regardless of the timeoutMs value you set.

Cause: A proxy or load balancer between your client and the Cells API is closing HTTP response streams after 30 seconds of no response body bytes. This is a common default for proxies (30-second server-idle timeout). The timeoutMs field controls the Cells server-side limit, not the proxy.

Workaround: Keep commands under 30 seconds where possible. If you need longer-running commands, ensure any proxy you control is configured to pass through SSE streams, or use a direct connection that bypasses the idle-killing proxy.

Diagnose

# Check the raw SSE stream for keepalive comment lines
curl -N -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/exec \
  -H "x-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd":["sleep","35"],"timeoutMs":300000}' | cat

# If the stream closes at exactly 30s, a proxy is killing idle connections.
# Use timeoutMs <= 30000 for commands that must complete within one network hop,
# or route traffic through a client that passes through SSE streams without timeout.
# Check the raw SSE stream for keepalive comment lines
curl -N -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/exec \
  -H "x-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd":["sleep","35"],"timeoutMs":300000}' | cat

# If the stream closes at exactly 30s, a proxy is killing idle connections.
# Use timeoutMs <= 30000 for commands that must complete within one network hop,
# or route traffic through a client that passes through SSE streams without timeout.

Preview URL returns 502

Symptom: After starting a service and calling the expose endpoint, requests to the session public URL return 502 immediately.

Cause: The service process has not finished starting up, or the routing layer has not yet propagated the new port mapping. Both take time after the API calls return.

Fix: Wait at least 10 seconds after receiving a successful response from the start-service endpoint before making requests to the preview URL. Use waitForPort: true and a reasonable timeoutMs (10 to 30 seconds) to let the service bind its port before the start-service call returns.

Wait before access

# Start service and wait, then check the URL
curl -X POST .../services \
  -d '{"name":"web","cmd":"node","args":["server.js"],"port":3000,"waitForPort":true,"timeoutMs":15000}'

# Wait at least 10 seconds before using the preview URL
sleep 10
curl https://SESSION_ID.sandbox.mudbase.dev/
# Start service and wait, then check the URL
curl -X POST .../services \
  -d '{"name":"web","cmd":"node","args":["server.js"],"port":3000,"waitForPort":true,"timeoutMs":15000}'

# Wait at least 10 seconds before using the preview URL
sleep 10
curl https://SESSION_ID.sandbox.mudbase.dev/

Session creation fails with 412 volume conflict

Symptom: Creating a new session when another session for the same organization is already running returns a 412 or 503 error about a volume conflict.

Cause: The infrastructure layer attaches a persistent volume per organization to each new session. A Fly volume can only be attached to one running machine at a time, so only one session can run per organization simultaneously.

Workaround: Close the existing session before creating a new one. Named cells (cellName) also require you to close the previous session before re-attaching. A fix for concurrent ephemeral sessions is in progress.

Command exits immediately with code -1

The command was killed by the session timeout or by the exec timeoutMs. Increase the timeout, or check that the session has not already ended (look up its status first).

alwaysOn returns 400

Always-on sessions require a Growth or Scale plan. If your organization is on a lower tier, the create call returns 400 with the message "alwaysOn sessions require a Growth or Scale sandbox plan." Upgrade your plan at cells.mudbase.dev/pricing to enable this feature.