Skip to main content
Learn how to resolve common errors when using Hopx Sandboxes.

​
Authentication Errors

​
Error: “Authentication failed”

Cause: Invalid or missing API key. Solution:
  • Python
  • JavaScript/TypeScript
import os
from hopx_ai import Sandbox

# ✅ Good: Check API key is set
api_key = os.getenv("HOPX_API_KEY")
if not api_key:
    raise ValueError("HOPX_API_KEY environment variable not set")

sandbox = Sandbox.create(template="code-interpreter", api_key=api_key)
Prevention:
  • Always set HOPX_API_KEY environment variable
  • Verify API key in dashboard
  • Rotate API keys regularly

​
Template Not Found

​
Error: “Template not found”

Cause: Invalid template name or template doesn’t exist. Solution:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# ✅ Good: Use correct template name
sandbox = Sandbox.create(template="code-interpreter")  # Correct

# ❌ Bad: Wrong template name
# sandbox = Sandbox.create(template="code_interpreter")  # Wrong
Prevention:
  • Use exact template names (case-sensitive)
  • List available templates using API or SDK
  • Check template availability before use

​
Code Execution Errors

​
Error: “Code execution failed”

Cause: Syntax errors, runtime errors, or timeout. Solution:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox
from hopx_ai.errors import CodeExecutionError

def execute_code_safe(code: str):
    """Execute code with error handling"""
    try:
        with Sandbox.create(template="code-interpreter") as sandbox:
            result = sandbox.run_code(code, timeout=30)
            
            if not result.success:
                print(f"Code failed: {result.stderr}")
                print(f"Exit code: {result.exit_code}")
                return None
            
            return result.stdout
    except CodeExecutionError as e:
        print(f"Execution error: {e.message}")
        return None

# Example
result = execute_code_safe("print(1/0)")  # Will fail
if result is None:
    print("Code execution failed")
Prevention:
  • Test code locally before executing in sandbox
  • Set appropriate timeouts
  • Handle errors gracefully
  • Check code syntax before execution

​
Timeout Errors

​
Error: “Request timed out”

Cause: Code execution exceeded timeout limit. Solution:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# ✅ Good: Set appropriate timeout
sandbox = Sandbox.create(template="code-interpreter")

# For long-running operations, increase timeout
result = sandbox.run_code("""
import time
time.sleep(10)  # Long operation
print("Done")
""", timeout=60)  # 60 seconds timeout
Prevention:
  • Set appropriate timeouts for your operations
  • Break long operations into smaller chunks
  • Monitor execution time

​
File Not Found Errors

​
Error: “File not found”

Cause: File doesn’t exist in sandbox filesystem. Solution:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox
from hopx_ai.errors import FileNotFoundError

def read_file_safe(sandbox: Sandbox, filepath: str):
    """Read file with error handling"""
    try:
        return sandbox.files.read(filepath)
    except FileNotFoundError:
        print(f"File not found: {filepath}")
        return None

with Sandbox.create(template="code-interpreter") as sandbox:
    # Create file first
    sandbox.files.write("/workspace/data.txt", "Hello")
    
    # Then read it
    content = read_file_safe(sandbox, "/workspace/data.txt")
Prevention:
  • Check file existence before reading
  • Use absolute paths
  • Create files before reading them

​
Rate Limit Errors

​
Error: “Rate limit exceeded”

Cause: Too many requests in a short time period. Solution:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox
from hopx_ai.errors import RateLimitError
import time

def execute_with_retry(code: str):
    """Execute with rate limit handling"""
    max_retries = 3
    for attempt in range(max_retries):
        try:
            with Sandbox.create(template="code-interpreter") as sandbox:
                return sandbox.run_code(code)
        except RateLimitError as e:
            if attempt < max_retries - 1:
                wait_time = e.retry_after if e.retry_after else 2 ** attempt
                time.sleep(wait_time)
                continue
            raise
Prevention:
  • Implement exponential backoff
  • Batch operations when possible
  • Monitor rate limit usage

​
Common Solutions Summary

  • Verify API key is set in environment variable
  • Check API key is valid in dashboard
  • Ensure API key has correct permissions
  • Use exact template names (case-sensitive)
  • Verify template exists before use
  • Check template availability
  • Test code locally first
  • Set appropriate timeouts
  • Handle errors gracefully
  • Check syntax before execution
  • Use absolute paths
  • Check file existence before reading
  • Create files before accessing them
  • Implement exponential backoff
  • Batch operations when possible
  • Monitor rate limit usage

​
Next Steps

Debugging Guide

Learn debugging techniques

Error Handling

Best practices for error handling

Error Reference

Complete error reference

Connection Issues

Troubleshoot connection problems