# Debug Sandbox Execution

Debug Python code execution failures by capturing partial traces, isolating failing...

- Repository: https://github.com/HKUDS/AgentPilot (7784 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add HKUDS/AgentPilot --skill debug-sandbox-execution -g -a claude-code -y`
Codex: `npx skills add HKUDS/AgentPilot --skill debug-sandbox-execution -g -a codex -y`
Cursor: `npx skills add HKUDS/AgentPilot --skill debug-sandbox-execution -g -a cursor -y`
Gemini CLI: `npx skills add HKUDS/AgentPilot --skill debug-sandbox-execution -g -a gemini-cli -y`

## Description

Debug Python code execution failures by capturing partial traces, isolating failing functions, and incrementally verifying outputs

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Debug Sandbox Execution Failures

When `execute_code_sandbox` fails with unknown errors or incomplete output, use this debugging pattern to identify the root cause and recover incrementally.

## Problem

The `execute_code_sandbox` tool may fail silently, truncate output, or produce opaque errors. Complex scripts with multiple file outputs are especially prone to partial failures.

## Solution

Use a three-phase debugging approach:

### Phase 1: Capture Partial Execution Traces

When a sandbox execution fails, rerun the code using `run_shell` with output piping to capture whatever output is produced before the failure:

```bash
python your_script.py 2>&1 | head -100
```

This reveals:
- Which functions/steps executed successfully
- Where the failure occurred
- Any error messages that were suppressed

### Phase 2: Isolate Failing Functions

Break the script into smaller, testable units. Execute each function or code block independently:

```python
# Test individual components
if __name__ == "__main__":
    # Step 1: Test imports
    import numpy as np
    print("Imports OK")
    
    # Step 2: Test function A in isolation
    result_a = function_a()
    print(f"Function A: {result_a}")
    
    # Step 3: Test function B
    result_b = function_b(result_a)
    print(f"Function B: {result_b}")
```

Run each section with `execute_code_sandbox` separately to identify which component fails.

### Phase 3: Incremental Output Generation

Generate output files one at a time, verifying each before proceeding:

```python
import numpy as np
import soundfile as sf

# Generate and save file 1
audio1 = np.random.randn(48000 * 10).astype(np.float32)
sf.write('output_01.wav', audio1, 48000, subtype='FLOAT')

# Verify file 1 exists and has expected properties
import os
assert os.path.exists('output_01.wav'), "File 1 not created"

# Generate and save file 2
audio2 = np.random.randn(48000 * 10).astype(np.float32)
sf.write('output_02.wav', audio2, 48000, subtype='FLOAT')

The rest: https://github.com/HKUDS/AgentPilot/blob/HEAD/openspace/benchmarks/gdpval/skills/debug-sandbox-execution/SKILL.md