debugging-troubleshooting-2025

What this skill does

## 🚨 CRITICAL GUIDELINES

### Windows File Path Requirements

**MANDATORY: Always Use Backslashes on Windows for File Paths**

When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).

**Examples:**
- ❌ WRONG: `D:/repos/project/file.tsx`
- ✅ CORRECT: `D:\repos\project\file.tsx`

This applies to:
- Edit tool file_path parameter
- Write tool file_path parameter
- All file operations on Windows systems


### Documentation Guidelines

**NEVER create new documentation files unless explicitly requested by the user.**

- **Priority**: Update existing README.md files rather than creating new documentation
- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise
- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone
- **User preference**: Only create additional .md files when user specifically asks for documentation


---

# Bash Debugging & Troubleshooting (2025)

## Overview

Comprehensive debugging techniques and troubleshooting patterns for bash scripts following 2025 best practices.

## Debug Mode Techniques

### 1. Basic Debug Mode (set -x)

```bash
#!/usr/bin/env bash
set -euo pipefail

# Enable debug mode
set -x

# Your commands here
command1
command2

# Disable debug mode
set +x

# Continue without debug
command3
```

### 2. Enhanced Debug Output (PS4)

```bash
#!/usr/bin/env bash
set -euo pipefail

# Custom debug prompt with file:line:function
export PS4='+(${BASH_SOURCE}:${LINENO}): ${FUNCNAME[0]:+${FUNCNAME[0]}(): }'

set -x
my_function() {
    local var="value"
    echo "$var"
}
my_function
set +x
```

**Output:**
```text
+(script.sh:10): my_function(): local var=value
+(script.sh:11): my_function(): echo value
value
```

### 3. Conditional Debugging

```bash
#!/usr/bin/env bash
set -euo pipefail

# Enable via environment variable
DEBUG="${DEBUG:-false}"

debug() {
    if [[ "$DEBUG" == "true" ]]; then
        echo "[DEBUG] $*" >&2
    fi
}

# Usage
debug "Starting process"
process_data
debug "Process complete"

# Run: DEBUG=true ./script.sh
```

### 4. Debugging Specific Functions

```bash
#!/usr/bin/env bash
set -euo pipefail

# Debug wrapper
debug_function() {
    local func_name="$1"
    shift

    echo "[TRACE] Calling: $func_name $*" >&2
    set -x
    "$func_name" "$@"
    local exit_code=$?
    set +x
    echo "[TRACE] Exit code: $exit_code" >&2
    return $exit_code
}

# Usage
my_complex_function() {
    local arg1="$1"
    # Complex logic
    echo "Result: $arg1"
}

debug_function my_complex_function "test"
```

## Tracing and Profiling

### 1. Execution Time Profiling

```bash
#!/usr/bin/env bash
set -euo pipefail

# Profile function execution time
profile() {
    local start_ns end_ns duration_ms
    start_ns=$(date +%s%N)

    "$@"
    local exit_code=$?

    end_ns=$(date +%s%N)
    duration_ms=$(( (end_ns - start_ns) / 1000000 ))

    echo "[PROFILE] '$*' took ${duration_ms}ms (exit: $exit_code)" >&2
    return $exit_code
}

# Usage
profile slow_command arg1 arg2
```

### 2. Function Call Tracing

```bash
#!/usr/bin/env bash
set -euo pipefail

# Trace all function calls
trace_on() {
    set -o functrace
    trap 'echo "[TRACE] ${FUNCNAME[0]}() called from ${BASH_SOURCE[1]}:${BASH_LINENO[0]}" >&2' DEBUG
}

trace_off() {
    set +o functrace
    trap - DEBUG
}

# Usage
trace_on
function1
function2
trace_off
```

### 3. Variable Inspection

```bash
#!/usr/bin/env bash
set -euo pipefail

# Inspect all variables at any point
inspect_vars() {
    echo "=== Variable Dump ===" >&2
    declare -p | grep -v "^declare -[^ ]*r " | sort >&2
    echo "===================" >&2
}

# Inspect specific variable
inspect_var() {
    local var_name="$1"
    echo "[INSPECT] $var_name = ${!var_name:-<unset>}" >&2
}

# Usage
my_var="test"
inspect_var my_var
inspect_vars
```

## Error Handling and Recovery

### 1. Trap-Based Error Handler

```bash
#!/usr/bin/env bash
set -euo pipefail

# Comprehensive error handler
error_handler() {
    local exit_code=$?
    local line_number=$1

    echo "ERROR: Command failed with exit code $exit_code" >&2
    echo "  File: ${BASH_SOURCE[1]}" >&2
    echo "  Line: $line_number" >&2
    echo "  Function: ${FUNCNAME[1]:-main}" >&2

    # Print stack trace
    local frame=0
    while caller $frame; do
        ((frame++))
    done >&2

    exit "$exit_code"
}

trap 'error_handler $LINENO' ERR

# Your script logic
risky_command
```

### 2. Dry-Run Mode

```bash
#!/usr/bin/env bash
set -euo pipefail

DRY_RUN="${DRY_RUN:-false}"

# Safe execution wrapper
execute() {
    if [[ "$DRY_RUN" == "true" ]]; then
        echo "[DRY-RUN] Would execute: $*" >&2
        return 0
    else
        "$@"
    fi
}

# Usage
execute rm -rf /tmp/data
execute cp file.txt backup/

# Run: DRY_RUN=true ./script.sh
```

### 3. Rollback on Failure

```bash
#!/usr/bin/env bash
set -euo pipefail

OPERATIONS=()

# Track operations for rollback
track_operation() {
    local rollback_cmd="$1"
    OPERATIONS+=("$rollback_cmd")
}

# Execute rollback
rollback() {
    echo "Rolling back operations..." >&2
    for ((i=${#OPERATIONS[@]}-1; i>=0; i--)); do
        echo "  Executing: ${OPERATIONS[$i]}" >&2
        eval "${OPERATIONS[$i]}" || true
    done
}

trap rollback ERR EXIT

# Example usage
mkdir /tmp/mydir
track_operation "rmdir /tmp/mydir"

touch /tmp/mydir/file.txt
track_operation "rm /tmp/mydir/file.txt"

# If script fails, rollback executes automatically
```

## Common Issues and Solutions

### 1. Script Works Interactively but Fails in Cron

**Problem:** Script runs fine manually but fails when scheduled.

**Solution:**
```bash
#!/usr/bin/env bash
set -euo pipefail

# Fix PATH for cron
export PATH="/usr/local/bin:/usr/bin:/bin"

# Set working directory
cd "$(dirname "$0")" || exit 1

# Log everything for debugging
exec 1>> /var/log/myscript.log 2>&1

echo "[$(date)] Script starting"
# Your commands here
echo "[$(date)] Script complete"
```

### 2. Whitespace in Filenames Breaking Script

**Problem:** Script fails when processing files with spaces.

**Debugging:**
```bash
#!/usr/bin/env bash
set -euo pipefail

# Show exactly what the script sees
debug_filename() {
    local filename="$1"
    echo "Filename: '$filename'" >&2
    echo "Length: ${#filename}" >&2
    hexdump -C <<< "$filename" >&2
}

# Proper handling
while IFS= read -r -d '' file; do
    debug_filename "$file"
    # Process "$file"
done < <(find . -name "*.txt" -print0)
```

### 3. Script Behaves Differently on Different Systems

**Problem:** Works on Linux but fails on macOS.

**Debugging:**
```bash
#!/usr/bin/env bash
set -euo pipefail

# Platform detection and debugging
detect_platform() {
    echo "=== Platform Info ===" >&2
    echo "OS: $OSTYPE" >&2
    echo "Bash: $BASH_VERSION" >&2
    echo "PATH: $PATH" >&2

    # Check tool versions
    for tool in sed awk grep; do
        if command -v "$tool" &> /dev/null; then
            echo "$tool: $($tool --version 2>&1 | head -1)" >&2
        fi
    done
    echo "====================" >&2
}

detect_platform

# Use portable patterns
case "$OSTYPE" in
    linux*)   SED_CMD="sed" ;;
    darwin*)  SED_CMD=$(command -v gsed || echo sed) ;;
    *)        echo "Unknown platform" >&2; exit 1 ;;
esac
```

### 4. Variable Scope Issues

**Problem:** Variables not available where expected.

**Debugging:**
```bash
#!/usr/bin/env bash
set -euo pipefail

# Show variable scope
test_scope() {
    local local_var="local"
    global_var="global"

    echo "Inside function:" >&2
    echo "  local_var=$local_var" >&2
    echo "  global_var=$global_var" >&2
}

test_scope

echo "Outside function:" >&2
echo "  local_var=${local_var:-<not set>}" >&2
echo "  global_var=${global_var:-<not set>}" >&2

# Subshell scope issue
echo "test" | (
    read -r value
    echo "In subshell: $value"
)
echo "After subshell: ${value:-<not set>}"  # Empty!
```

## Interactive Debugging

### 1. Breakpoint Pattern

```bash
#!/usr/b