StackSplain 🔍

Stop looking at those stupid error messages and use StackSplain to explain it in plain english.

Install with:

(global)
bun install -g stacksplain
npm install -g stacksplain

What it does

Takes this mess:

TypeError: Cannot read property 'map' of undefined
    at processData (app.js:23:15)

And gives you this:

🔍 Tried to access 'map' on something that doesn't exist

What happened:
  Your code tried to read a property called 'map', but the object 
  it was trying to read from is null or undefined.

Why this might have happened:
  • The variable might not have been initialized yet
  • An async operation might not have completed
  • A function might have returned null/undefined unexpectedly

How to fix it:
  ✓ Check if the object exists before accessing 'map'
  ✓ Use optional chaining: object?.property
  ✓ Add a null check: if (object) { ... }

Install

Global install with Bun:

bun install -g stacksplain

Global install with npm:

npm install -g stacksplain

Or use directly with npx (no install):

npx stacksplain "your error message"

Quick install script:

curl -fsSL https://raw.githubusercontent.com/jeeting/stacksplain/main/install.sh | bash

Usage

Copy error, run command:

stacksplain --clipboard

Pipe errors directly:

node broken-script.js 2>&1 | stacksplain

Pass as argument:

stacksplain "ReferenceError: foo is not defined"

Specify language:

stacksplain --lang python "AttributeError: 'NoneType' object has no attribute 'append'"
stacksplain -l py --file error.log

Read from file:

stacksplain --file error.log

Shell shortcuts

Add to your .zshrc or .bashrc:

alias ss='stacksplain'
alias ssc='stacksplain --clipboard'

# Wrap any command
explain() {
  "$@" 2>&1 | stacksplain
}

Then:

explain npm test
ss "your error here"
ssc  # explains clipboard

What errors?

100+ patterns across 11 categories:

JavaScript/TypeScript:

• Type Errors - null refs, not a function, type issues
• Reference Errors - undefined variables, scope problems
• Syntax Errors - missing brackets, typos, invalid code
• Range Errors - stack overflow, invalid lengths
• Network Errors - fetch fails, CORS, timeouts, 404s, 503s
• Promise Errors - unhandled rejections, await issues
• JSON Errors - parse failures, invalid syntax
• Module Errors - import/export problems, circular deps
• DOM Errors - element not found, invalid selectors

Python:

• AttributeError - missing attributes, NoneType errors
• ValueError - conversion errors, unpacking issues
• TypeError - type mismatches, unsupported operations
• KeyError - missing dictionary keys

More Python errors coming soon!

See ERROR_LIST.md for the complete list.

Examples

TypeError:

$ stacksplain "TypeError: x.map is not a function"

🔍 Tried to call something that isn't a function

What happened:
  You used parentheses () to call something, but that thing isn't actually a function.

Why this might have happened:
  • The variable might be undefined or null
  • You might have a typo in the function name
  • The function might not be exported/imported correctly

Network Error:

$ stacksplain "Error: ECONNREFUSED connect to localhost:3000"

🔍 Server refused the connection

What happened:
  Tried to connect to server but it actively refused.

Why this might have happened:
  • Server not running
  • Wrong port number
  • Firewall blocking connection

Module Error:

$ stacksplain "Error: Cannot find module 'express'"

🔍 Module import failed

What happened:
  Tried to import a module that can't be found.

Why this might have happened:
  • Package not installed
  • Wrong import path
  • Typo in module name

How to fix it:
  ✓ Run npm install or yarn install
  ✓ Check import path is correct

Promise Error:

$ stacksplain "UnhandledPromiseRejectionWarning: Error: API call failed"

🔍 Promise was rejected but nobody caught it

What happened:
  An async operation failed but you didn't add a .catch() or try/catch to handle it.

How to fix it:
  ✓ Add .catch() to promise chains
  ✓ Wrap await calls in try/catch blocks

Python AttributeError:

$ stacksplain -l py "AttributeError: 'NoneType' object has no attribute 'append'"

🔍 'append' doesn't exist on this object

What happened:
  Tried to access an attribute that doesn't exist on the object.

Why this might have happened:
  • Typo in attribute name
  • Object is None
  • Wrong object type

How to fix it:
  ✓ Check spelling of attribute name
  ✓ Verify object is not None
  ✓ Use hasattr() to check: if hasattr(obj, 'attr')

Python with file:

$ stacksplain --lang python --file traceback.log

🔍 'list' object has no attribute 'push'

What happened:
  Tried to access an attribute that doesn't exist on the object.

How to fix it:
  ✓ Use .append() instead of .push() for Python lists
  ✓ Check object type with type(obj)

Contributing

Want to add more errors? Edit the JSON files in src/database/:

{
  "your_error": {
    "patterns": ["text to match in error"],
    "summary": "Brief description",
    "whatHappened": "What actually happened",
    "whyItHappened": ["Reason 1", "Reason 2"],
    "howToFix": ["Solution 1", "Solution 2"]
  }
}

Development

bun install
bun start "your error message"

Why Bun?

Fast and runs TypeScript natively. No build step needed.

License

MIT

Made by jeeting with lots of love and care (: (thank you ai for this readme!)