runtime-error-explainer

Runtime Error Explainer

Analyze runtime and compilation errors with clear explanations and actionable fixes.

Core Capabilities

This skill helps debug runtime and compilation errors by:

1. Parsing error output - Extract key information from error messages and stack traces
2. Identifying root causes - Determine why errors occur during execution or compilation
3. Explaining clearly - Translate technical errors into understandable language
4. Providing fixes - Suggest concrete code changes with before/after examples
5. Preventing recurrence - Recommend best practices to avoid similar errors

Error Analysis Workflow

Step 1: Gather Error Context

Collect all relevant information about the error.

Essential Information:

• Complete error message and stack trace
• Programming language and version
• Code that triggered the error
• How the error was triggered (command, action, input)

Additional Context (if available):

• Recent code changes
• Environment details (OS, IDE, dependencies)
• Input data or parameters that caused error
• Configuration files

How to Gather:

# Python - Run with full traceback
python script.py

# Python - More verbose error output
python -v script.py

# Java - Compile with verbose output
javac -verbose MyClass.java

# Java - Run with stack trace
java -XX:+ShowCodeDetailsInExceptionMessages MyClass

Step 2: Categorize the Error

Identify the error type using references/error_catalog.md:

Error Categories:

1. Syntax/Compilation Errors
2. Python: SyntaxError, IndentationError
3. Java: Compilation errors (missing semicolons, type errors)

1. Runtime Errors
2. Python: TypeError, AttributeError, ValueError, KeyError, IndexError
3. Java: NullPointerException, IllegalArgumentException, ArrayIndexOutOfBoundsException

1. Import/Dependency Errors
2. Python: ImportError, ModuleNotFoundError
3. Java: ClassNotFoundException, NoClassDefFoundError

1. Type Errors
2. Python: TypeError (wrong types in operations)
3. Java: Type mismatch compilation errors

1. Name/Reference Errors
2. Python: NameError, UnboundLocalError
3. Java: Variable not initialized, cannot find symbol

Step 3: Extract Key Information

Pull out critical details from the error.

From Error Message:

• Error type and name
• Error description
• Line number where error occurred
• File name
• Variable names or values involved

From Stack Trace:

• Execution path leading to error
• Function/method call chain
• Origin of error in your code vs. library code

Example Python Error:

Traceback (most recent call last):
  File "app.py", line 45, in <module>
    result = process_user(None)
  File "app.py", line 12, in process_user
    return user.name.upper()
AttributeError: 'NoneType' object has no attribute 'name'

Extracted Information:

• Error type: AttributeError
• Problem: Tried to access .name on None
• Location: app.py line 12, in process_user function
• Root cause: user parameter is None

Step 4: Identify Root Cause

Analyze why the error occurred.

Common Root Causes:

Syntax/Compilation:

• Missing or mismatched parentheses/brackets
• Incorrect indentation (Python)
• Missing semicolons (Java)
• Typos in keywords or variable names

Runtime:

• Null/None values where objects expected
• Wrong data types in operations
• Index out of bounds
• Missing dictionary keys
• Division by zero
• File not found

Import/Dependency:

• Module/package not installed
• Incorrect import path
• Circular imports
• Classpath issues (Java)

See references/error_catalog.md for detailed root cause analysis for each error type.

Step 5: Provide Explanation

Structure the explanation with clear sections.

Explanation Template:

## Error Summary

[One-sentence description of what went wrong]

## What Happened

[Explain the error in plain language]

**Error Type:** [Error name and category]
**Location:** [File and line number]
**Problem:** [What specifically failed]

## Root Cause

[Explain why this happened - the underlying issue]

## How to Fix

### Solution 1: [Most common fix] ⭐

[Specific code change or action]

Before

[problematic code]

After

[fixed code]

**Why this works:** [Brief explanation]

### Solution 2: [Alternative approach]

[Another fix if Solution 1 doesn't apply]

## Verification

[How to verify the fix works]

[command to test]

## Prevention

[How to avoid this error in future]

- [Best practice 1]
- [Best practice 2]
- [Tool or technique recommendation]

Step 6: Suggest Next Steps

Provide actionable debugging guidance.

If fix is straightforward:

• Show exact code change
• Provide command to verify
• Mention related code to review

If more investigation needed:

• Suggest adding print/logging statements
• Recommend debugging tools
• Propose simplification to isolate issue

If environmental issue:

• Suggest checking installation/versions
• Recommend environment verification
• Propose configuration review

Common Error Patterns

Python: AttributeError - NoneType

Error:

AttributeError: 'NoneType' object has no attribute 'method_name'

Explanation:

## Error Summary
Attempted to call a method on None instead of an object instance.

## What Happened

**Error Type:** AttributeError
**Problem:** Code tried to access an attribute or method on `None`

Python functions return `None` by default if no explicit return statement is
used. When you try to call a method on `None`, you get this error.

## Root Cause

Common causes:
1. Function didn't return a value but you expected an object
2. Variable not initialized before use
3. Database/API query returned no result
4. Method called before object creation

## How to Fix

### Solution 1: Add None check ⭐

Before

result = get_user(user_id) name = result.name # Crashes if result is None

After

result = get_user(user_id) if result is not None: name = result.name else: name = "Unknown"

**Why this works:** Defensively handles the case where `get_user` returns None.

### Solution 2: Fix the source function to always return a value

Before

def get_user(user_id): if user_id in users: return users[user_id] # Implicitly returns None

After

def get_user(user_id): if user_id in users: return users[user_id] return User(id=user_id, name="Guest") # Return default user

### Solution 3: Use walrus operator with conditional (Python 3.8+)

Assign and check in one line

if (result := get_user(user_id)) is not None: name = result.name

## Verification

python script.py

## Prevention

- Always check return values before using them
- Use type hints: `def get_user(user_id: int) -> Optional[User]:`
- Add assertions: `assert result is not None, "User not found"`
- Use Optional type and handle None explicitly

Python: ImportError / ModuleNotFoundError

Error:

ModuleNotFoundError: No module named 'requests'

Explanation:

## Error Summary
Python cannot find the module you're trying to import.

## What Happened

**Error Type:** ModuleNotFoundError (Python 3) or ImportError (Python 2)
**Problem:** The module is not installed or not in Python's path

## Root Cause

1. Package not installed via pip
2. Wrong virtual environment activated
3. Typo in module name
4. Package installed in different Python version

## How to Fix

### Solution 1: Install the missing package ⭐

Install package

pip install requests

Or if using Python 3 explicitly

pip3 install requests

Or with specific Python version

python -m pip install requests

**Why this works:** Makes the package available to your Python environment.

### Solution 2: Activate correct virtual environment

Check current environment

which python

Activate virtual environment

source venv/bin/ac