Python Error Encyclopedia: The Emergency Kit for Developers

📖 Introduction

Every programmer makes mistakes. However, the difference between a beginner and a pro is simply how fast they fix them. Therefore, consider this guide your personal Emergency Kit.

When your code crashes, do not stare at the terminal in confusion. Instead, find your error message below to understand exactly why it happened and, most importantly, how to fix it. We have cataloged over 100 specific crash scenarios, ranging from simple typos to complex Data Science memory leaks.

🛑 1. Syntax Errors (The Code Won’t Start)

These errors happen before your code even runs. Typically, this means you made a typo, forgot a character, or broke a grammar rule. Consequently, Python cannot understand your instructions until these are fixed.

Common Punctuation & Typos

Invalid Syntax: This is arguably the most common error. For instance, you likely forgot a colon :, a parenthesis ), or a quote mark '.[ How to Fix: SyntaxError: invalid syntax in Python ]
Comparison vs. Assignment: A classic typo. Specifically, you wrote a simple = (assignment) inside an if statement when you meant == (comparison). [ How to Fix: SyntaxError: invalid syntax. Maybe you meant ‘==’ or ‘:=’? ]
Unclosed Brackets: This occurs when you open a parenthesis ( or a bracket [ on one line but never close it. As a result, Python gets confused on the next line. [ How to Fix: SyntaxError: unexpected EOF while parsing ]
String Errors: You started a string with a quote but hit “Enter” without closing it. Therefore, this causes a line-break error. [ How to Fix: SyntaxError: EOL while scanning string literal ]
Unterminated Strings: Similarly, this happens if you have text strings that weren’t closed properly before the file ended. [ How to Fix: SyntaxError: unterminated string literal ]

Indentation & Structure

Unexpected Indent: Python relies strictly on spaces. If you mix tabs and spaces, or indent a line that shouldn’t be indented, this error triggers. [ How to Fix: IndentationError: unexpected indent in Python ]
Matching Indentation: Conversely, this happens when you indented a block, but then un-indented it too far (or not enough) to match the previous level. [ How to Fix: IndentationError: unindent does not match any outer indentation level ]
Reserved Words: You tried to use a reserved word (like True, False, or None) as a variable name. However, Python does not allow this. [ How to Fix: SyntaxError: cannot assign to True ]
Generator Expressions: A generator expression inside a function call needs its own parentheses. Otherwise, Python cannot parse it. [ How to Fix: SyntaxError: Generator expression must be parenthesized]
Return Placement: You tried to use the return keyword in the main body of your script. However, return is only valid inside a function. [ How to Fix: SyntaxError: ‘return’ outside function ]

🔍 2. Runtime Errors (Crashes Logic)

The code starts running but crashes when it hits a specific line. In general, these are logic errors where you try to do something impossible.

Variable & Name Issues

Undefined Name: You tried to use a variable that doesn’t exist yet. Alternatively, you might have simply misspelled it. [ How to Fix: NameError: name ‘x’ is not defined in Python ]
Deletion Errors: You tried to delete a variable using del. However, that variable didn’t exist in the first place. [ How to Fix: NameError: name ‘…’ is not defined (A Deep Dive) ]
Scope Conflicts: You are using a variable inside a function that has the same name as a global variable. Consequently, this causes a scope conflict. [ How to Fix: UnboundLocalError: local variable referenced before assignment ]

Type & Attribute Mismatches

Calling Non-Functions: You tried to loop over None or call a variable like a function. For example, treating a variable as if it were a command. [ How to Fix: TypeError: ‘NoneType’ object is not callable ]
String Calls: Similarly, you tried to call a string like a function, usually by accidentally adding () after it. [ How to Fix: TypeError: ‘str’ object is not callable in Python ]
List Index: You tried to grab item #10 from a list. However, that list only has 5 items. [ How to Fix: IndexError: list index out of range in Python ]
NoneType Attributes: This is often called the “Ghost” error. Specifically, you are trying to access a method on a variable that is empty (None). [ How to Fix: AttributeError: ‘NoneType’ object has no attribute ‘x’ ]

Data Structure Conflicts

List Methods: You tried to use .split() on a list. But, that method only belongs to strings. [ How to Fix: AttributeError: ‘list’ object has no attribute ‘split’ ]
String Appends: You tried to .append() to a string. Since strings are immutable, you must use concatenation instead. [ How to Fix: AttributeError: ‘str’ object has no attribute ‘x’ ]
Argument Mismatch: You passed 2 arguments to a function. However, that function only accepts 1. [ How to Fix: TypeError: method takes 1 positional argument but 2 were given ]
Unhashable Keys: You tried to use a dictionary as a key in another dictionary. Because keys must be immutable, this is not allowed. [ How to Fix: TypeError: unhashable type: ‘dict’ ]
Infinite Recursion: Your code is talking to itself in an infinite circle. Therefore, you must set a “base case” to break the loop. [ How to Fix: RecursionError: maximum recursion depth exceeded ]

📦 3. Import & Setup Errors

These are issues with your “Environment.” Usually, your code is fine, but Python cannot find the libraries or files it needs.

Library & Path Issues

Missing Modules: You installed a library, but Python can’t find it. Typically, this is a virtual environment issue. [ How to Fix: ModuleNotFoundError: No module named ‘pandas’ ]
Scikit-Learn Naming: Specifically for Scikit-Learn users, the package name is tricky (sklearn vs scikit-learn). [ How to Fix: ModuleNotFoundError: No module named ‘sklearn’ (Package Names vs. Imports) ]
Circular Imports: The file exists, but the specific function you want isn’t there. Often, this is caused by circular imports or bad file naming. [ How to Fix: ImportError: cannot import name ‘X’ from ‘Y’ ]
Missing Files: You tried to read a file. However, it does not exist at that specific path. [ How to Fix: FileNotFoundError: [Errno 2] No such file or directory ]

Database & JSON

JSON Errors: You tried to read a JSON file. But, the file is either empty or formatted badly. [ How to Fix: json.decoder.JSONDecodeError: Expecting value ]
Database Locks: Your database is invisible. Therefore, you need to fix the paths and permissions blocking your SQLite connection. [ How to Fix: sqlite3.OperationalError: no such table: users ]
Connection Refused: The “Waiting Room” is closed. Consequently, your Python app can’t talk to Redis or Celery. [ How to Fix: redis.exceptions.ConnectionError: Error 111 ]

🧮 4. Math, Logic & Data Types

The code runs, but the calculation fails or the data is the wrong shape.

Calculation Failures

Invalid Literals: You tried to calculate the square root of -1, or convert “text” into a number. As a result, Python throws a Value error. [ How to Fix: ValueError: invalid literal for int() with base 10 ]
Float Conversion: Similarly, you tried to turn a string with a decimal (like “10.5”) directly into an integer. [ How to Fix: ValueError: invalid literal for int() with base 10: ‘10.5’ ]
Zero Division: You tried to divide a number by zero. Fortunately, Python protects the universe by stopping you. [ How to Fix: ZeroDivisionError: division by zero ]

Data Shape Mismatches

Type Operations: You tried to do math with a list and a string, or a string and an integer. Obviously, these types are incompatible. [ How to Fix: TypeError: unsupported operand type(s) for +: ‘int’ and ‘str’ ]
Unpacking Errors: You tried to unpack a list into variables (e.g., x, y = list). However, the list had too many items. [ How to Fix: ValueError: not enough values to unpack (expected X, got Y) ]
NumPy Shapes: A NumPy error. Specifically, you tried to shove a sequence (list) into a single array element. [ How to Fix: ValueError: setting an array element with a sequence ]

📊 5. Data Science Specifics (Polars & AI)

Specialized errors for Data Analysts and Engineers using Polars, Pandas, and PyTorch.

Pandas & Polars Errors

Ambiguous Truth: You are using if df['col'] > 0 in Pandas. This fails because a Series has multiple Truth values. [ How to Fix: ValueError: The truth value of a Series is ambiguous ]
Index Mismatch: You tried to create a DataFrame. However, your data columns are different lengths. [ How to Fix: ValueError: Length of values does not match length of index ]
Merge Conflicts: You tried to merge two DataFrames. Unfortunately, they don’t share a common column name. [ How to Fix: MergeError: No common columns to perform merge on ]

AI & Memory Issues

CUDA Memory: Your AI model is too big for your graphics card. In this case, we show you how to use quantization. [ How to Fix: RuntimeError: CUDA out of memory (PyTorch & Hugging Face) ]

🎓 Bonus: How to Read a Traceback

Don’t be intimidated by the wall of text. Here is how to read an error message like a pro:

Ignore the Middle: First, if you are using libraries (like Pandas), the middle of the traceback is internal library code. Look for your filenames to see where your logic triggered the crash.
Start at the Bottom: Python prints the most recent error last. Therefore, the bottom line tells you what happened (e.g., SyntaxError).
Look Up: Finally, the line above the error tells you where it happened (File name and Line number).