Skip to main content
This page covers common errors you may encounter when using Moru and how to resolve them.

​
Error Types

​
SandboxError / SandboxException

Base class for all Moru errors. Catch this to handle any Moru error. 
from moru.exceptions import SandboxException

try:
    sandbox = Sandbox.create()
except SandboxException as e:
    print(f"Moru error: {e}")

​
TimeoutError / TimeoutException

Raised when an operation times out. Common causes:
  • Sandbox creation took too long
  • Command exceeded timeout
  • Network issues
Solutions:
  • Increase timeout value
  • Check network connectivity
  • Use a template with pre-installed dependencies
from moru.exceptions import TimeoutException

try:
    result = sandbox.commands.run("long_command", timeout=300)
except TimeoutException:
    print("Command timed out, consider increasing timeout")

​
NotFoundError / NotFoundException

Resource not found - sandbox, template, or file doesn’t exist. Common causes:
  • Sandbox was terminated
  • Template doesn’t exist
  • File path is incorrect
from moru.exceptions import NotFoundException

try:
    sandbox = Sandbox.connect("sbx_nonexistent")
except NotFoundException:
    print("Sandbox not found - it may have been terminated")

​
AuthenticationError / AuthenticationException

Authentication failed - invalid or missing API key. Solutions:
  • Verify your API key is correct
  • Check if the key has necessary permissions
  • Ensure MORU_API_KEY environment variable is set
from moru.exceptions import AuthenticationException

try:
    sandbox = Sandbox.create()
except AuthenticationException:
    print("Invalid API key - check your MORU_API_KEY")

​
RateLimitError

Too many requests - rate limit exceeded. Solutions:
  • Wait and retry with exponential backoff
  • Reduce request frequency
  • Contact support for higher limits
import time
from moru.exceptions import SandboxException

def create_with_retry(max_retries=3):
    for attempt in range(max_retries):
        try:
            return Sandbox.create()
        except SandboxException as e:
            if "rate limit" in str(e).lower():
                wait = 2 ** attempt
                print(f"Rate limited, waiting {wait}s...")
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")

​
NotEnoughSpaceError / NotEnoughSpaceException

Disk space exhausted in sandbox. Solutions:
  • Delete unnecessary files
  • Use a larger disk quota
  • Start fresh with a new sandbox
from moru.exceptions import NotEnoughSpaceException

try:
    sandbox.files.write("/large_file", large_data)
except NotEnoughSpaceException:
    print("Disk full - delete files or create new sandbox")

​
CommandExitError / CommandExitException

Command exited with non-zero exit code. 
from moru.exceptions import CommandExitException

try:
    result = sandbox.commands.run("python script.py")
except CommandExitException as e:
    print(f"Command failed with exit code {e.exit_code}")
    print(f"stderr: {e.stderr}")

​
TemplateError / TemplateException

Template incompatibility or version issues. Solutions:
  • Rebuild the template
  • Update to a newer template version
  • Check template build logs

​
BuildError / BuildException

Template build failed. Solutions:
  • Check build logs
  • Verify Dockerfile is correct
  • Ensure dependencies are available

​
Common Issues

​
”Sandbox not responding”

The sandbox may have timed out or crashed.
  1. Check if sandbox is still running: sandbox.is_running()
  2. Check sandbox logs via CLI: moru sandbox logs sbx_id
  3. Create a new sandbox if needed

​
”Connection refused”

Network connectivity issues.
  1. Verify internet connectivity
  2. Check if sandbox allows outbound connections
  3. Verify the port is correct for getHost()

​
”Permission denied”

File or command permission issues.
  1. Use user="root" for privileged operations
  2. Check file permissions with sandbox.files.get_info()
  3. Ensure template has correct user setup

​
Error Handling Pattern

from moru import Sandbox
from moru.exceptions import (
    SandboxException,
    TimeoutException,
    NotFoundException,
    AuthenticationException,
)

def run_in_sandbox():
    try:
        sandbox = Sandbox.create()
        try:
            result = sandbox.commands.run("python script.py")
            return result.stdout
        finally:
            sandbox.kill()
    except AuthenticationException:
        raise ValueError("Invalid API key")
    except NotFoundException:
        raise ValueError("Template not found")
    except TimeoutException:
        raise TimeoutError("Operation timed out")
    except SandboxException as e:
        raise RuntimeError(f"Sandbox error: {e}")

​
Getting Help

If you encounter persistent issues:
  1. Check the dashboard for system status
  2. Review sandbox logs for detailed error messages
  3. Report issues at github.com/moru-ai