Troubleshooting

​

Diagram 1: Fast triage flow

​

Setup and startup failures

​

Docker unreachable

• isol8 setup fails early with Docker check errors
• local isol8 run fails before code runs

docker info

• start Docker daemon/Desktop
• ensure current user can access Docker socket

​

isol8 serve fails: missing API key

• [ERR] API key required...

isol8 serve --key my-secret-key

export ISOL8_API_KEY=my-secret-key
isol8 serve

​

isol8 serve fails in built CLI mode with platform/binary errors

• unsupported platform (os-arch)
• server binary not found for version

• verify platform is supported
• force refresh:

isol8 serve --update

• if release artifact is missing, use Bun/dev path temporarily (bun run dev -- serve ...)

​

Standalone server arg parse errors

• invalid port
• unknown argument

• use:

isol8 serve --port 3000 --key my-secret-key

• avoid unsupported flags in standalone mode

​

isol8 serve fails because port is in use

• EADDRINUSE
• startup fails on localhost:3000

• current behavior prompts you to:
  • enter another port, or
  • let isol8 find an available port automatically
• to set a port non-interactively, use precedence:
  1. --port
  2. ISOL8_PORT
  3. PORT
  4. fallback 3000

​

Input and runtime resolution failures

​

File not found

• [ERR] File not found: ...

ls -la path/to/file.py

• correct file path
• or use inline mode:

isol8 run -e "print('ok')" --runtime python

​

Runtime auto-detect fails

• [ERR] Cannot detect runtime for ...

• file extension not mapped in runtime registry

isol8 run script.unknown --runtime python

​

Deno inline execution fails

• Deno adapter requires a file path — inline code is not supported.

• run Deno from a file (.mts) instead of -e

​

Unknown runtime error

• Unknown runtime: "..."

• use one of: python, node, bun, deno, bash

​

Resource limit and output issues

​

Timeout failures

• long-running process terminated near timeout limit

• command is wrapped with timeout and killed on expiry

isol8 run script.py --timeout 60000

​

Memory limit format errors

• Invalid memory limit format: "..."

• use accepted formats like 512m, 1g, 256k, or bytes

isol8 run script.py --memory 1g

​

OOM / abrupt kill

• process exits unexpectedly, often with kill-like behavior

• increase memory and/or reduce workload footprint:

isol8 run heavy.py --memory 2g

​

Output truncated

• CLI warning: [WARN] Output was truncated
• result has truncated: true

isol8 run noisy.py --max-output 10485760

​

Package installation and filesystem issues

​

Package install fails (exit code + stderr)

• Package install failed (exit code ...): ...

• validate package names
• confirm runtime package source accessibility (if using networked install)

• test smaller package set first
• prefer pre-baked dependencies via isol8 setup for production stability

​

Native extension problems

• import/load issues for native libs (.so)

• executable paths required for native extension loading

• keep installs in /sandbox (default behavior)
• increase sandbox capacity if needed:

isol8 run script.py --sandbox-size 1g

​

Persistence, sessions, and file API issues

​

No active container. Call execute() first in persistent mode.

• local putFile/getFile fails immediately

• no persistent container has been initialized yet

• run one execute() first in persistent mode, then file APIs

​

Runtime switch rejected in persistent mode

• Cannot switch runtime from "python" to "node"...

• create separate persistent engine/session per runtime

​

Session not found in remote file/session calls

• 404 Session not found

• missing or stale session id

• initialize session with /execute using same sessionId
• verify session not auto-pruned

​

Sessions disappearing unexpectedly

• inspect:
  • cleanup.autoPrune
  • cleanup.maxContainerAgeMs

• increase idle window or delete sessions explicitly at end of workflow

​

Networking and security policy failures

​

Filtered mode blocks expected hosts

• outbound requests fail in --net filtered

isol8 run net.py \
  --net filtered \
  --allow "^api\\.openai\\.com$" \
  --log-network

• correct regex to match exact hostname
• remember blacklist wins over whitelist

​

Filtered mode setup errors (proxy/iptables)

• Proxy failed to start within timeout
• Failed to set up iptables rules...

• container-level startup issue
• capability/environment constraints

• retry with --debug and inspect logs
• validate Docker environment and image health

​

Network logs missing

• no networkLogs in result

• both must be true:
  • network: "filtered"
  • logNetwork: true

​

Seccomp/profile issues

• seccomp profile load errors before execution

• verify security.customProfilePath if using custom profile
• keep security.seccomp: "strict" for default hardening; standalone binaries can use the embedded default profile when on-disk profile files are absent
• if strict/custom profile loading fails, execution is blocked by design

​

Remote API and client errors

​

401 vs 403 auth failures

• API rejects request

• 401: missing Authorization header
• 403: invalid Bearer token

​

Remote health check failures

• Remote server health check failed: ...

curl -sS http://localhost:3000/health

• verify host/port
• confirm server process is running

​

Streaming client errors

• Stream failed: ...
• No response body for streaming

• verify endpoint availability and proxy behavior
• test with non-streaming /execute first to isolate issue

​

Remote file operations fail in client

• File operations require a sessionId (persistent mode)

• instantiate RemoteIsol8 with sessionId for file operations

​

High-signal debug playbook

1. Reproduce with debug logs:

isol8 run script.py --debug

2. Inspect effective config:

isol8 config --json

3. Minimize to simplest repro:

• inline code
• explicit runtime
• no packages
• --net none

4. Add options back one by one:

• network
• install packages
• persistence/session
• custom limits

5. For remote issues, test raw endpoints with curl before SDK integration.

​

FAQ

​

Related pages