Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python IndexError: Causes, Fixes, and Prevention

Understand why Python raises IndexError, how to trace the faulty index, and how to prevent out-of-range access with bounds checks and exception handling.

~3 min readPython
#IndexError#exception handling#list indexing#debugging
Illustration of a Python list as a row of blocks with a red X marking an out-of-range position beyond the last block.

Python raises IndexError when code attempts to access an element at a position that does not exist in a sequence. Lists, tuples, strings, and other sequence types raise the exception when the requested index falls outside the valid range. IndexError is a subclass of LookupError, which is itself an Exception subclass, so it can be caught with except IndexError, except LookupError, or a broader handler.

python
items = ["alpha", "beta", "gamma"] print(items[3])

This raises:

text
IndexError: list index out of range

The message varies by sequence type. A string raises IndexError: string index out of range, and a tuple raises IndexError: tuple index out of range. The mechanism is identical: the index is outside the valid range.

How Zero-Based Indexing Produces Out-of-Range Access

Python sequences are zero-indexed. For a non-empty sequence with n elements, valid indices run from 0 through n - 1; the final valid index is one less than the length, which is a frequent source of off-by-one errors.

python
values = [10, 20, 30] print(len(values)) # 3 print(values[0]) # 10 print(values[2]) # 30 print(values[3]) # IndexError

Negative indices count backward from the end. values[-1] returns 30, values[-2] returns 20, and values[-3] returns 10. For a non-empty sequence, the most negative valid index is -len(values). Accessing values[-4] raises IndexError just as values[3] does.

Common Code Patterns That Trigger IndexError

A frequent trigger is a loop that uses range(len(sequence)) and accidentally steps one position past the end:

python
data = [5, 10, 15] for i in range(len(data) + 1): print(data[i])

The loop runs four times, but the last iteration accesses data[3], which does not exist. Using range(len(data)) or iterating directly over the list avoids the problem.

Another common case is reading the first element of a sequence that may be empty:

python
rows = fetch_rows() # may return [] first = rows[0]

When fetch_rows() returns an empty list, this line raises IndexError. Checking if rows: before accessing rows[0] prevents the failure.

Reading the Traceback to Find the Faulty Index

The traceback identifies the exact line where the exception occurred. The final frame shows the source line and the file path. For a computed index, the traceback alone does not reveal the index value, so you need to inspect the variables involved.

python
def select(records, position): return records[position] select(["a", "b"], 5)

The traceback points to records[position] but does not print position. Adding a temporary print or using a debugger to inspect position and len(records) is the fastest way to confirm which value caused the failure.

Preventing IndexError With Bounds Checks

The simplest guard is an explicit length check before access:

python
def safe_first(items): if len(items) == 0: return None return items[0]

For a computed index, check it against both ends of the sequence:

python
def get_item(sequence, index): if -len(sequence) <= index < len(sequence): return sequence[index] raise ValueError(f"index {index} out of range for length {len(sequence)}")

Raising ValueError with a descriptive message is often more useful than letting IndexError propagate, because the message documents the actual index and length.

Using try/except IndexError for Dynamic Indexes

When the index comes from user input, a file, or another external source, a bounds check may not be practical. Catching IndexError at the boundary of the operation keeps the failure contained:

python
try: result = records[user_index] except IndexError: result = None

This pattern is appropriate when the index is genuinely unpredictable. It should not be used to mask a bug in your own indexing logic. If the index is derived from a known sequence length, a bounds check is clearer and cheaper.

IndexError With Empty Sequences and Negative Indices

Empty sequences have no valid indices at all. [][0], ""[0], and ()[0] all raise IndexError. Slices behave differently: [][0:1] returns an empty list because slicing never raises IndexError regardless of the bounds.

For a non-empty sequence, negative indices follow the same boundary rule: items[-len(items)] is valid, but items[-len(items) - 1] raises IndexError. This matters when you compute a negative offset from a variable length and do not account for the exact boundary.

Performance and Maintainability Tradeoffs

A length check adds a constant-time comparison before each access, which can matter in a tight loop. Catching IndexError is cheap when no exception is raised, but expensive when one is, because building the exception object and unwinding the stack has real cost. Use try/except where an out-of-range index is plausible but not part of normal control flow.

For maintainability, prefer explicit bounds checks in application code and reserve try/except IndexError for boundary code that consumes untrusted input. This keeps the control flow visible and avoids hiding indexing mistakes behind a broad exception handler.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.