Python StopIteration — What It Means & How to Fix It

What Does This Error Mean?

StopIteration is a signal that an iterator has run out of items to give you. Normally this is handled automatically by for loops — they catch it quietly and stop looping. You only see this as an error when you manually call next() on an iterator and it has nothing left to return.

Affected Models

Python 2.x
Python 3.x
All Python versions

Common Causes

Calling next() on an iterator that has already been fully consumed
Using next() without a default value on an empty iterator
Raising StopIteration inside a generator function — in Python 3.7+ this converts to a RuntimeError
Trying to iterate over a generator a second time (generators can only be iterated once)
A manual iterator pattern where the stopping condition was not handled properly

How to Fix It

If you are manually calling next(), always provide a default value as the second argument. Example: next(my_iterator, None) returns None instead of raising StopIteration when exhausted.

next(iterator, default) is the safe version. next(iterator) with no default will raise StopIteration when the iterator runs out.
Use a for loop instead of next() whenever possible. A for loop handles StopIteration automatically and cleanly stops when the iterator is exhausted.

A for loop is almost always cleaner and safer than manually calling next().
If you need to iterate over a generator more than once, convert it to a list first: items = list(my_generator). Then you can loop over items as many times as you want.

Remember: generators can only be iterated once. Once consumed, they are empty.
If you are writing a generator function and intentionally raise StopIteration to end it, use 'return' instead. In Python 3.7+, raising StopIteration inside a generator causes a RuntimeError.

Simply write 'return' to end a generator function. Python automatically signals StopIteration to any code iterating over it.
When writing a custom iterator class (__iter__ and __next__ methods), make sure your __next__ raises StopIteration when items are exhausted. This is the correct protocol.

A custom __next__ that never raises StopIteration will cause an infinite loop in any for loop that uses it.

When to Call a Professional

StopIteration is always something you can fix yourself. Use a for loop instead of manually calling next() unless you have a specific reason to use next(). If you must use next(), always provide a default value.

Frequently Asked Questions

Why does StopIteration not always show as an error?

Because for loops catch it silently. A for loop internally calls next() on the iterator and, when StopIteration is raised, it knows the iteration is done and exits the loop cleanly. You only see it as a visible error when YOU are calling next() directly and do not catch it.

Can I reuse a generator after it is exhausted?

No — generators are single-use. Once you have iterated through all of a generator's values, it is empty and cannot be reset. If you need to iterate multiple times, convert the generator to a list first: data = list(my_generator). Or call the generator function again to create a fresh generator object.

What is the difference between an iterator and a generator?

A generator is a special kind of iterator created with a function that uses the 'yield' keyword. All generators are iterators, but not all iterators are generators. Both follow the same protocol — they have a __next__ method and raise StopIteration when exhausted. Generators are just a convenient way to create iterators without writing a full class.