---

name: runtime-error-explainer description: Explains runtime errors and compilation failures with actionable debugging guidance. Use when Python or Java code throws runtime exceptions (NullPointerException, TypeError, AttributeError, etc.), compilation errors (syntax errors, type mismatches, import failures), or dependency issues. Analyzes error messages, stack traces, and code context to identify root causes and provide concrete fixes with examples. Distinct from test-related errors - focuses on errors during normal code execution and build processes.

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

   • Python: SyntaxError, IndentationError
   • Java: Compilation errors (missing semicolons, type errors)

2. Runtime Errors

   • Python: TypeError, AttributeError, ValueError, KeyError, IndexError
   • Java: NullPointerException, IllegalArgumentException, ArrayIndexOutOfBoundsException

3. Import/Dependency Errors

   • Python: ImportError, ModuleNotFoundError
   • Java: ClassNotFoundException, NoClassDefFoundError

4. Type Errors

   • Python: TypeError (wrong types in operations)
   • Java: Type mismatch compilation errors

5. Name/Reference Errors

   • Python: NameError, UnboundLocalError
   • 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]

```[language]
# 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:**

```markdown
## 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 ⭐

```python
# 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:**

```markdown
## 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 ⭐

```bash
# 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/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Install package in virtual environment
pip install requests

Solution 3: Check for typos

# Wrong
import reqests  # Typo

# Correct
import requests

Verification

python -c "import requests; print('Success')"

Prevention

• Use requirements.txt: pip install -r requirements.txt
• Use virtual environments for project isolation
• Document all dependencies
• Use pip freeze > requirements.txt to capture dependencies

### Java: NullPointerException

**Error:**

Exception in thread "main" java.lang.NullPointerException at com.example.MyClass.process(MyClass.java:25)

**Explanation:**

```markdown
## Error Summary
Attempted to use an object reference that is null.

## What Happened

**Error Type:** NullPointerException
**Location:** MyClass.java, line 25
**Problem:** Tried to access a method or field on a null object

## Root Cause

Common causes:
1. Object not initialized before use
2. Method returned null unexpectedly
3. Array element is null
4. Forgotten to instantiate object

## How to Fix

### Solution 1: Add null check ⭐

```java
// Before
String name = user.getName().toUpperCase();

// After
if (user != null && user.getName() != null) {
    String name = user.getName().toUpperCase();
} else {
    String name = "UNKNOWN";
}

Why this works: Prevents accessing methods on null references.

Solution 2: Use Optional (Java 8+)

// Before
public User getUser(int id) {
    return userMap.get(id);  // Returns null if not found
}

String name = getUser(123).getName();  // NPE if user not found

// After
public Optional<User> getUser(int id) {
    return Optional.ofNullable(userMap.get(id));
}

String name = getUser(123)
    .map(User::getName)
    .orElse("Unknown");

Solution 3: Initialize objects properly

// Before
private User user;  // Field is null by default

public void process() {
    user.getName();  // NullPointerException
}

// After
private User user = new User();  // Initialize at declaration

// Or in constructor
public MyClass() {
    this.user = new User();
}

Solution 4: Use Objects utility (Java 7+)

import java.util.Objects;

// Throw meaningful exception if null
Objects.requireNonNull(user, "User must not be null");
String name = user.getName();

Verification

javac MyClass.java && java MyClass

Prevention

• Initialize all object fields
• Use Optional for potentially null values
• Add @Nullable/@NonNull annotations
• Enable null-safety warnings in IDE
• Consider using Objects.requireNonNull() for critical parameters

### Java: ClassNotFoundException

**Error:**

java.lang.ClassNotFoundException: com.example.MyClass at java.net.URLClassLoader.findClass(URLClassLoader.java:382)

**Explanation:**

```markdown
## Error Summary
Java cannot find the specified class at runtime.

## What Happened

**Error Type:** ClassNotFoundException
**Problem:** Class exists in source code but not found when running

## Root Cause

1. Class not in classpath
2. Package name doesn't match directory structure
3. .class file not compiled
4. Typo in class name
5. JAR file not included

## How to Fix

### Solution 1: Check classpath ⭐

```bash
# Compile with source files in correct package structure
javac -d bin src/com/example/MyClass.java

# Run with classpath pointing to bin directory
java -cp bin com.example.MyClass

Why this works: Ensures compiled .class files are in classpath.

Solution 2: Verify package structure matches directories

Project structure should be:
src/
  com/
    example/
      MyClass.java

// MyClass.java must declare matching package
package com.example;

public class MyClass {
    public static void main(String[] args) {
        System.out.println("Hello");
    }
}

Solution 3: Include JAR files in classpath

# If MyClass is in external JAR
java -cp "lib/mylib.jar:." com.example.MyClass

# Windows (use semicolon)
java -cp "lib/mylib.jar;." com.example.MyClass

Solution 4: Use Maven/Gradle (recommended)

Maven automatically manages classpaths.

<!-- pom.xml -->
<dependencies>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>my-library</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

Verification

# Check if class file exists
ls bin/com/example/MyClass.class

# Verify package declaration matches
head -1 src/com/example/MyClass.java

Prevention

• Use build tools (Maven, Gradle) to manage dependencies
• Follow Java package naming conventions
• Keep package declarations synchronized with directory structure
• Use IDE features to auto-manage imports and packages

### Python: SyntaxError

**Error:**

File "script.py", line 10 if x == 5 ^ SyntaxError: invalid syntax

**Explanation:**

```markdown
## Error Summary
Code has syntax error preventing Python from parsing it.

## What Happened

**Error Type:** SyntaxError
**Location:** Line 10
**Problem:** Missing colon at end of if statement

## Root Cause

Python syntax violated - common causes:
- Missing colons after if/for/while/def/class
- Unmatched parentheses/brackets
- Incorrect indentation
- Invalid operator usage

## How to Fix

### Solution 1: Add missing colon ⭐

```python
# Before
if x == 5
    print("Five")

# After
if x == 5:
    print("Five")

Why this works: Python requires colon to start code blocks.

Solution 2: Check for unmatched brackets

# Before
result = calculate(a, b, (c + d)
print(result)

# After
result = calculate(a, b, (c + d))
print(result)

Solution 3: Fix indentation

# Before (mixing tabs and spaces)
def my_function():
    x = 5
  return x  # Indentation error

# After (consistent spaces)
def my_function():
    x = 5
    return x

Verification

# Python will parse file without running
python -m py_compile script.py

# Or just run it
python script.py

Prevention

• Use IDE with syntax highlighting
• Enable linting (pylint, flake8)
• Use auto-formatters (black, autopep8)
• Configure editor to show whitespace characters

### Java: Type Mismatch Compilation Error

**Error:**

MyClass.java:15: error: incompatible types: int cannot be converted to String String result = 42; ^

**Explanation:**

```markdown
## Error Summary
Trying to assign value of wrong type to variable.

## What Happened

**Error Type:** Compilation error - type mismatch
**Location:** Line 15
**Problem:** Assigning int (42) to String variable

## Root Cause

Java is statically typed - variables can only hold values of declared type
or compatible types.

## How to Fix

### Solution 1: Convert type explicitly ⭐

```java
// Before
String result = 42;

// After
String result = String.valueOf(42);
// or
String result = Integer.toString(42);
// or
String result = "" + 42;  // Concatenation with empty string

Why this works: Explicitly converts int to String.

Solution 2: Change variable type

// Before
String result = 42;

// After
int result = 42;

Solution 3: Use correct literal type

// Before (assigning int to double)
double price = 10;  // Works but not ideal

// After (use double literal)
double price = 10.0;

Verification

javac MyClass.java

Prevention

• Use proper type conversions
• Be aware of implicit type casting rules
• Use IDE suggestions for quick fixes
• Understand primitive types vs object types (int vs Integer)

## Language-Specific Notes

### Python Error Characteristics

**Common Patterns:**
- Runtime errors only (no compilation phase)
- Clear stack traces with file/line numbers
- Descriptive error messages
- Exception hierarchy (all inherit from BaseException)

**Key Files to Check:**
- Module `__init__.py` for package imports
- `sys.path` for import resolution
- Virtual environment activation

**Debugging Tools:**
```bash
# Interactive debugging
python -m pdb script.py

# Print traceback programmatically
import traceback
traceback.print_exc()

Java Error Characteristics

Common Patterns:

• Compilation errors vs runtime errors
• Less descriptive error messages than Python
• Line numbers in stack traces
• Checked vs unchecked exceptions

Key Files to Check:

• pom.xml (Maven) or build.gradle (Gradle)
• Package structure matches directory structure
• CLASSPATH environment variable

Debugging Tools:

# Verbose compilation
javac -verbose MyClass.java

# Show detailed exception messages (Java 14+)
java -XX:+ShowCodeDetailsInExceptionMessages MyClass

# Using debugger
jdb MyClass

Quick Reference: Error Categories

Category	Python Examples	Java Examples	Common Fix
Null/None errors	AttributeError on None	NullPointerException	Add null checks
Type errors	TypeError	Type mismatch error	Fix types or convert
Import errors	ModuleNotFoundError	ClassNotFoundException	Check imports/classpath
Syntax errors	SyntaxError	Compilation errors	Fix syntax
Index errors	IndexError	ArrayIndexOutOfBoundsException	Check array bounds
Name errors	NameError	Cannot find symbol	Fix variable names
Key errors	KeyError	-	Check dict keys exist

Resources

• references/error_catalog.md - Comprehensive catalog of Python and Java errors with detailed examples, root causes, and solutions
• references/debugging_guide.md - Systematic debugging strategies, tools, and techniques for complex errors

Best Practices

1. Read the full error message - Don't skip stack traces
2. Identify error location - Line number and file are critical
3. Understand the error type - Each type has typical causes
4. Check recent changes - Often errors relate to recent edits
5. Reproduce consistently - Ensure error happens reliably
6. Simplify to isolate - Remove code until error disappears
7. Use debugging tools - Debuggers are more powerful than print statements
8. Fix root cause, not symptoms - Adding try/except without understanding hides problems
9. Add defensive code - Null checks, type validation prevent errors
10. Learn from errors - Understand why it happened to prevent recurrence