TypeError: cannot unpack non-iterable object (tested fix)

TypeError: cannot unpack non-iterable NoneType object (or int, bool, float) means you wrote a, b = something and something was a single value, not a tuple. We reproduced each variant in Python 3.13 and tested the fixes.

1. A function that returns a tuple on one path and None on another

This is the usual cause of the NoneType version. The function returns a pair when it finds something and falls off the end otherwise:

def find(items, target):
    for i, x in enumerate(items):
        if x == target:
            return i, x
    # falls off the end: returns None

for target in ("b", "z"):
    try:
        index, value = find(["a", "b"], target)
        print(target, "->", index, value)
    except TypeError as e:
        print(target, "->", type(e).__name__ + ":", e)

Output:

b -> 1 b
z -> TypeError: cannot unpack non-iterable NoneType object

Add an explicit return for the not-found path, such as return None, None or raise ValueError(...), or check the result before unpacking.

2. An early return with a single value

The bool, int and float versions usually come from an early-exit branch that returns one value while the main path returns two:

def check(n):
    if n < 0:
        return False            # early exit returns one value...
    return True, n * 2          # ...normal path returns two

for n in (3, -1):
    try:
        ok, doubled = check(n)
        print(n, "->", ok, doubled)
    except TypeError as e:
        print(n, "->", type(e).__name__ + ":", e)

Output:

3 -> True 6
-1 -> TypeError: cannot unpack non-iterable bool object

Make every return in the function give the same shape, for example return False, None.

3. The type name tells you what came back

cases = {
    "int":   lambda: 42,
    "float": lambda: 3.5,
    "bool":  lambda: True,
    "None":  lambda: None,
    "len":   lambda: len,
}
for name, make in cases.items():
    try:
        a, b = make()
    except TypeError as e:
        print(f"{name:8}", type(e).__name__ + ":", e)

Output:

int      TypeError: cannot unpack non-iterable int object
float    TypeError: cannot unpack non-iterable float object
bool     TypeError: cannot unpack non-iterable bool object
None     TypeError: cannot unpack non-iterable NoneType object
len      TypeError: cannot unpack non-iterable builtin_function_or_method object

The last word before object is the type of the value on the right of =. builtin_function_or_method means you unpacked a builtin like len without calling it.

4. Forgetting the () on your own function

def get_size():
    return (640, 480)

try:
    width, height = get_size     # forgot the ()
except TypeError as e:
    print(type(e).__name__ + ":", e)
width, height = get_size()
print(width, height)

Output:

TypeError: cannot unpack non-iterable function object
640 480

5. In a for loop you get a different message

count = 3
try:
    for i, item in count:
        pass
except TypeError as e:
    print(type(e).__name__ + ":", e)

items = ["a", "b"]
try:
    for i, item in len(items):
        pass
except TypeError as e:
    print(type(e).__name__ + ":", e)

for i, item in enumerate(items):
    print(i, item)

Output:

TypeError: 'int' object is not iterable
TypeError: 'int' object is not iterable
0 a
1 b

for i, item in count fails while iterating count, before any unpacking, so the message is 'int' object is not iterable. Use enumerate(items) or range(len(items)).

6. When the value is iterable: ValueError instead

for value in ("ab", "abc", [1], {"x": 1, "y": 2}):
    try:
        a, b = value
        print(repr(value), "->", a, b)
    except ValueError as e:
        print(repr(value), "->", type(e).__name__ + ":", e)

Output:

'ab' -> a b
'abc' -> ValueError: too many values to unpack (expected 2)
[1] -> ValueError: not enough values to unpack (expected 2, got 1)
{'x': 1, 'y': 2} -> x y

Strings and dicts unpack without error when the length happens to match. Unpacking a dict gives its keys, and a two-character string gives two characters. Related: too many values to unpack, object is not iterable and 'NoneType' object is not subscriptable.

Written with AI assistance. Measured on 2026-10-22 on Debian with Python 3.13.5 (the type-name table also in the official python:3.8-alpine image, identical): functions that return None or a single bool, int/float/bool/None/builtin values, an uncalled function, for-loop unpacking, and str/list/dict right-hand sides. Every block was run verbatim and its output pasted unedited. PlainHeaders is our extension; Python is free.