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)

1. Runtime Errors

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

1. Import/Dependency Errors

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

1. Type Errors

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

1. 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]

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/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:

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

// 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:

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

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:

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

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:

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

// 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:

# 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

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