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: