🚨 Python Error Guide: 'IndexError: list index out of range' — Cause, Fix, and Troubleshooting Guide

Overview

Python raises IndexError: list index out of range when you access a position that doesn’t exist in a sequence:

IndexError: list index out of range

Indices run from 0 to len(seq) - 1; anything at or beyond the length (or below -len(seq)) is out of range. In automation scripts this usually means a list came back shorter than assumed — an empty query result, a line that split into fewer fields than expected, or an off-by-one loop bound. The list isn’t malformed; your code assumed an element that isn’t there.

Symptoms

• The traceback ends in IndexError: list index out of range at a seq[i] access.
• It works on typical inputs but fails on empty results, short lines, or the last iteration of a loop.
• line.split()[3] fails on a blank line or a row with fewer columns.
• Accessing results[0] when a search or API call returned an empty list.

Common Root Causes

• Empty list indexed — items[0] when items == [] (a query/filter returned nothing).
• Split produced fewer fields — parts = line.split(","); parts[4] on a short or blank line.
• Off-by-one loop bound — for i in range(len(a)+1): a[i] or using <= where < was meant.
• Assuming a fixed shape from variable data (optional trailing columns, ragged CSV).
• Popping/removing while iterating, shrinking the list under the index.
• Negative index past the start — a[-3] on a 2-element list.

Diagnostic Workflow

Print the length and the value before indexing:

print(len(parts), repr(parts))    # is it as long as you assumed?

Guard and log the offending input:

try:
    field = line.split(",")[4]
except IndexError:
    print(f"short line: {line!r}")
    raise

For loop bounds, prefer iterating the sequence directly rather than by index:

for item in items:      # no index arithmetic to get wrong
    ...

Example Root Cause Analysis

A log parser extracted the fifth field of each line:

for line in open("access.log"):
    status = line.split()[8]      # HTTP status is field 9
    counts[status] += 1

It ran for a while, then died:

IndexError: list index out of range

Printing the length on failure showed a blank line at the end of the file:

0 ['']... actually len 0 for '' -> split() gave []

A trailing empty line ('') split into an empty list, so [8] was out of range. The fix skips blank/short lines and validates the field count before indexing:

for line in open("access.log"):
    fields = line.split()
    if len(fields) < 9:
        continue                  # skip blank or malformed lines
    counts[fields[8]] += 1

Guarding on len(fields) makes the parser resilient to blank lines, partial writes, and format drift instead of crashing on the first oddity.

Prevention Best Practices

• Check len() before indexing variable-length data, or catch IndexError at the boundary and skip/log.
• Iterate directly (for x in seq) instead of for i in range(len(seq)) to eliminate index arithmetic.
• Handle empty results explicitly — if results: first = results[0] rather than assuming at least one.
• Use safe extraction — next(iter(seq), default) for “first or default”, or slicing (seq[3:4]) which returns [] instead of raising.
• Unpack with a star for ragged rows — first, *rest = parts tolerates extra fields.
• Validate input shape (expected column count) when parsing CSV/logs, and skip lines that don’t match.

Quick Command Reference

if len(seq) > i: x = seq[i]        # bounds check before access
first = results[0] if results else None   # empty-safe first element
first = next(iter(seq), None)      # first-or-default, no IndexError
chunk = seq[i:i+1]                 # slice returns [] instead of raising
a, *rest = parts                   # tolerate extra trailing fields
for item in items: ...             # iterate values, not indices

Related Guides

• Bash & Python Error Guide: ‘TypeError: NoneType object is not subscriptable’ — the related error when the sequence itself is None.
• Python Error Guide: ‘KeyError’ — the dictionary equivalent of accessing something that isn’t there.
• Python Error Guide: ‘ValueError: invalid literal for int() with base 10’ — another failure from unvalidated parsed data.

Conclusion

IndexError: list index out of range means you indexed past the end of a sequence — usually a list that came back shorter than assumed: an empty result, a blank line, a short split, or an off-by-one bound. Check len() before indexing (or catch and skip), iterate values instead of indices, and handle the empty case explicitly. Validating shape at the data boundary turns “crashes on the first odd line” into predictable, resilient parsing.