arabelatso/runtime-error-explainer
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.
npx skills add https://github.com/ArabelaTso/Skills-4-SE --skill runtime-error-explainerAnalyze runtime and compilation errors with clear explanations and actionable fixes.
This skill helps debug runtime and compilation errors by:
Collect all relevant information about the error.
Essential Information:
Additional Context (if available):
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
Identify the error type using references/error_catalog.md:
Error Categories:
Pull out critical details from the error.
From Error Message:
From Stack Trace:
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:
AttributeError.name on Noneapp.py line 12, in process_user functionuser parameter is NoneAnalyze why the error occurred.
Common Root Causes:
Syntax/Compilation:
Runtime:
Import/Dependency:
See references/error_catalog.md for detailed root cause analysis for each error type.
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]
[problematic code]
[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]
Provide actionable debugging guidance.
If fix is straightforward:
If more investigation needed:
If environmental issue:
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 ⭐
result = get_user(user_id)
name = result.name # Crashes if result is None
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
def get_user(user_id):
if user_id in users:
return users[user_id]
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+)
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
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 ⭐
pip install requests
pip3 install requests
python -m pip install requests
**Why this works:** Makes the package available to your Python environment.
### Solution 2: Activate correct virtual environment
which python
source venv/bin/activate # Linux/Mac
venv\Scripts\activate # Windows
pip install requests
### Solution 3: Check for typos
import reqests # Typo
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
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
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 ⭐
javac -d bin src/com/example/MyClass.java
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
java -cp "lib/mylib.jar:." com.example.MyClass
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
ls bin/com/example/MyClass.class
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
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 ⭐
if x == 5
print("Five")
if x == 5:
print("Five")
**Why this works:** Python requires colon to start code blocks.
### Solution 2: Check for unmatched brackets
result = calculate(a, b, (c + d)
print(result)
result = calculate(a, b, (c + d))
print(result)
### Solution 3: Fix indentation
def my_function():
x = 5
return x # Indentation error
def my_function():
x = 5
return x
## Verification
python -m py_compile script.py
python script.py
## Prevention
- Use IDE with syntax highlighting
- Enable linting (pylint, flake8)
- Use auto-formatters (black, autopep8)
- Configure editor to show whitespace characters
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)
Common Patterns:
Key Files to Check:
__init__.py for package importssys.path for import resolutionDebugging Tools:
# Interactive debugging
python -m pdb script.py
# Print traceback programmatically
import traceback
traceback.print_exc()
Common Patterns:
Key Files to Check:
pom.xml (Maven) or build.gradle (Gradle)Debugging Tools:
# Verbose compilation
javac -verbose MyClass.java
# Show detailed exception messages (Java 14+)
java -XX:+ShowCodeDetailsInExceptionMessages MyClass
# Using debugger
jdb MyClass
| 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 |
references/error_catalog.md - Comprehensive catalog of Python and Java errors with detailed examples, root causes, and solutionsreferences/debugging_guide.md - Systematic debugging strategies, tools, and techniques for complex errors10. Learn from errors - Understand why it happened to prevent recurrence
Take arabelatso/runtime-error-explainer from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.
The instructions reference pip.
Without those the skill loads but fails at the first command.