explain-error

Turn stack traces into plain English.

Stop staring at cryptic error messages. Get instant, actionable explanations for any stack trace.

explain-error crash.log

┌─────────────────────────────────┐
│  Error Analysis [Python]        │
└─────────────────────────────────┘

What Happened
  Your application failed to connect to the PostgreSQL database.
  The database server at localhost:5432 is not accepting connections.

Likely Root Cause
  The PostgreSQL server is either not running, or it's not configured
  to accept TCP/IP connections on port 5432.

Suggested Fixes
  1. Check if PostgreSQL is running: sudo systemctl status postgresql
  2. Start the service if stopped: sudo systemctl start postgresql
  3. Verify pg_hba.conf allows connections from localhost
  4. Check if the port is correct in your connection string

Helpful References
  - PostgreSQL connection troubleshooting documentation
  - SQLAlchemy connection error handling guide

Confidence: high

---

Why explain-error?

• Language-agnostic - Works with Python, JavaScript, Java, Go, Rust, and more
• Cloud-native - Understands Docker, Kubernetes, and cloud provider logs
• Zero config - Just point it at your error log
• Privacy-first - Your logs stay local (except for LLM API calls)
• Actionable - Get fixes you can actually use, not generic advice

---

Installation

pip install explain-error

Set your Gemini API key:

export GEMINI_API_KEY="your-api-key-here"

Get a free API key at Google AI Studio.

---

Usage

Analyze a file

explain-error error.log

Pipe from another command

python app.py 2>&1 | explain-error

kubectl logs pod/web-app | explain-error

docker logs container_id 2>&1 | explain-error

Options

explain-error crash.log --lang python     # Specify language
explain-error crash.log --concise         # Shorter output
explain-error crash.log --format markdown # Markdown output

Option	Description	Default
--lang, -l	Language hint (auto, python, js, java, go)	auto
--concise, -c	Shorter, focused output	off
--format, -f	Output format (text, markdown)	text
--api-key, -k	Gemini API key	$GEMINI_API_KEY

---

Supported Languages & Runtimes

Language	Stack Traces	Common Errors
Python	Tracebacks	ImportError, TypeError, KeyError, etc.
JavaScript/Node.js	V8 traces	ReferenceError, ENOENT, MODULE_NOT_FOUND
Java/JVM	Exception chains	NullPointerException, ClassNotFoundException
Go	Panic traces	nil pointer, deadlock, race conditions
Rust	Panic backtraces	thread panic, borrowing errors
Ruby	Exception traces	NoMethodError, LoadError
PHP	Stack traces	Fatal errors, exceptions

Cloud & Infrastructure

• Docker - Container errors, OCI runtime issues
• Kubernetes - Pod failures, CrashLoopBackOff, ImagePullBackOff
• AWS/GCP/Azure - IAM errors, connection issues, service errors

---

Examples

Python - Database Connection Error

$ explain-error examples/python_error.log

Input

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError)
connection to server at "localhost" (127.0.0.1), port 5432 failed:
Connection refused

Output:

Your PostgreSQL database server isn't running or isn't accepting connections. Run sudo systemctl start postgresql and verify the connection settings.

---

Node.js - Missing Module

$ cat examples/node_error.log | explain-error

Input

Error: Cannot find module 'express'
Require stack:
- /home/user/project/src/server.js

Output:

The 'express' package is not installed. Run npm install express in your project directory.

---

Kubernetes - Pod Failure

$ kubectl describe pod web-app | explain-error --concise

Output:

Image pull failed due to authentication error. Add registry credentials to your cluster with kubectl create secret docker-registry.

---

How It Works

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Read Log   │────▶│   Detect     │────▶│    Parse     │
│  file/stdin  │     │  Language    │     │ Stack Trace  │
└──────────────┘     └──────────────┘     └──────────────┘
                                                 │
                                                 ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Display    │◀────│   Format     │◀────│   Analyze    │
│   Output     │     │   Results    │     │  with LLM    │
└──────────────┘     └──────────────┘     └──────────────┘

1. Read - Load error content from file or stdin, with smart truncation for large logs
2. Detect - Pattern matching to identify the language/runtime
3. Parse - Extract error messages, stack frames, and context
4. Analyze - Send structured prompt to Gemini 3 Flash for analysis
5. Format - Display results with Rich terminal formatting

---

Configuration

Environment Variables

Variable	Description
GEMINI_API_KEY	Your Google Gemini API key (required)

Supported File Extensions

.log, .txt, .out, .err, .trace

---

Contributing

Contributions are welcome! Here's how to get started:

git clone https://github.com/vmishra/explain-error.git
cd explain-error
pip install -e ".[dev]"

Development Commands

# Run tests
pytest

# Run linter
ruff check .

# Run type checker
mypy explain_error

Adding Language Support

1. Add detection patterns in explain_error/detector.py
2. Add parsing patterns in explain_error/parser.py
3. Create prompt template in explain_error/prompts/

---

Limitations

• Requires internet connection for LLM analysis
• API rate limits apply based on your Gemini plan
• Very large logs are truncated (first 500 + last 500 lines)
• Analysis quality depends on error verbosity

---

Roadmap

• Offline mode with local models (Ollama)
• VS Code extension
• Shell integration (auto-run on command failure)
• Custom prompt templates
• Error pattern learning

---

License

MIT License - see LICENSE

---

Related Projects

• wtfpython - Python gotchas
• tldr - Simplified man pages
• howdoi - Instant coding answers

---

Stop deciphering. Start fixing.