shell-error-debug-workflow

Shell Error Debug Workflow

When run_shell returns an 'unknown error' or ambiguous failure, apply this systematic troubleshooting workflow to diagnose and resolve the issue.

When to Use This Skill

• run_shell returns an 'unknown error' message
• Shell command fails without clear error output
• Command works locally but fails in the agent environment
• Intermittent or unexplained shell failures

Step-by-Step Troubleshooting Workflow

Step 1: Capture Explicit Stderr

Redirect stderr to stdout to capture all error output:

# Instead of:
run_shell command="some-command"

# Use:
run_shell command="some-command 2>&1"

This ensures error messages are captured in the output rather than being lost.

Step 2: Verify Working Directory

Confirm the current working directory and its contents:

run_shell command="pwd && ls -la"

Check that:

• You're in the expected directory
• Required files/directories exist
• Permissions are correct

Step 3: Check Tool/Command Availability

Verify the required command or tool exists and is accessible:

run_shell command="which some-command || command -v some-command || type some-command"

If the tool is not found, check PATH or install the required package.

Step 4: Use Absolute Paths

Replace relative paths with absolute paths to avoid directory-related issues:

# Instead of:
run_shell command="python script.py"

# Use:
run_shell command="$(pwd)/script.py"
# or
run_shell command="/absolute/path/to/script.py"

Step 5: Test with Minimal Command

Isolate the issue by running a minimal version of the command:

# Test basic functionality first
run_shell command="echo 'test'"

# Then gradually add complexity
run_shell command="some-command --version"
run_shell command="some-command --help"

Step 6: Check Environment Variables

Some commands depend on specific environment variables:

run_shell command="env | grep -i relevant_var"

Complete Diagnostic Sequence