Python LookupError — What It Means & How to Fix It

What Does This Error Mean?

LookupError is the base class for errors that happen when you try to look something up in a collection and it is not there. The two most common types are IndexError (looking up a list position that does not exist) and KeyError (looking up a dictionary key that does not exist). If you see LookupError directly, it is usually from a codec lookup — like trying to use an encoding name Python does not recognise.

Affected Models

Python 2.x
Python 3.x
All Python versions

Common Causes

Accessing a list, tuple, or string index that is out of bounds — raises IndexError (a subclass of LookupError)
Accessing a dictionary key that does not exist — raises KeyError (a subclass of LookupError)
Using an encoding name that Python does not recognise in codecs.lookup() or str.encode()
Catching 'except LookupError' in your own code and then seeing the error propagate
Third-party code uses LookupError as a base for its own custom lookup failures

How to Fix It

Read the full error message to find out if it is actually an IndexError or a KeyError — those are the most common subtypes.

IndexError: list index out of range. KeyError: 'my_key'. Both are LookupErrors but have different fixes.
For IndexError: check the length of your list before accessing by index. Use len(my_list) and make sure your index is less than that number.

Remember Python indexes start at 0. A list with 3 items has indexes 0, 1, and 2 — index 3 does not exist.
For KeyError: use .get() to safely retrieve a dictionary value instead of square bracket notation. my_dict.get('key', default_value) returns the default if the key is missing instead of raising an error.

Or check first with: if 'key' in my_dict: before accessing it.
If you see LookupError from a codec operation, check the encoding name you are using. Common valid names include 'utf-8', 'ascii', 'latin-1', 'cp1252'.

Encoding names are case-insensitive and hyphens vs underscores usually both work (utf-8 and utf_8 are the same), but misspellings will cause a LookupError.
To catch all lookup-type errors in one except block, catch LookupError — it will catch both IndexError and KeyError at once.

Example: except LookupError as e: print(f'Could not find item: {e}') — useful when you want to handle both types the same way.

When to Call a Professional

LookupError is always something you can fix yourself. Find out whether you are dealing with an IndexError or a KeyError, then fix the lookup to only request items that actually exist in the collection.

Frequently Asked Questions

What is the difference between LookupError, IndexError, and KeyError?

LookupError is the parent class. IndexError and KeyError are both children of LookupError. IndexError is specifically for lists, tuples, and strings when the position number is out of range. KeyError is specifically for dictionaries when the key does not exist. Catching LookupError catches all three at once.

When would I catch LookupError instead of IndexError or KeyError?

When you want to handle both types the same way in one except block. For example, if your function might get either a list index or a dictionary key and you just want to return None for any missing item, catching LookupError is cleaner than catching both separately.

Why did Python create LookupError as a parent class?

For the same reason all object-oriented languages create parent classes — to group related things together. It lets you write code that handles a whole category of errors at once. It also makes Python's exception hierarchy logical and readable.