Fix ValueError: too many values to unpack (expected 2)

You unpack a value and Python stops you:

ValueError: too many values to unpack (expected 2)

Or the mirror version:

ValueError: not enough values to unpack (expected 2, got 1)

Both say the same thing in different directions: the number of variables on the left doesn't match the number of values on the right. Python's unpacking is strict — two targets need exactly two values, no more, no fewer.

The fix is almost always one of three things: you miscounted, you're iterating a dict the wrong way, or a string split into more pieces than you expected. This guide covers each, plus the star-unpacking trick that makes the whole class of error go away.

Quick Answer

too many values to unpack (expected 2) means you assigned an iterable with more items than variables, like a, b = (1, 2, 3). Count both sides — targets must equal values. The most common cause is for k, v in my_dict (use my_dict.items()). Fix it by matching counts, limiting str.split(sep, maxsplit), or absorbing extras with a, b, *rest.

TL;DR

• Count both sides — targets on the left must equal values on the right.
• for k, v in d: is the classic bug → use d.items().
• Star-unpack to absorb extras: a, b, *rest = values.
• str.split(sep, maxsplit) caps parts so unpacking stays exact.
• "not enough values" is the same error in reverse.
• Debug with print(len(x), x) right before unpacking.

Count Both Sides

Every unpacking assignment has two sides, and their counts must match:

a, b = (1, 2)        # ✅ 2 targets, 2 values
a, b = (1, 2, 3)     # ❌ 2 targets, 3 values → too many values to unpack
a, b = (1,)          # ❌ 2 targets, 1 value  → not enough values to unpack

That's the whole rule. Everything below is a case where the right-hand side has a different count than you thought.

Triage by Where the Values Come From

Cause 1: Iterating a dict directly (the #1 case)

Looping over a dict yields its keys, not pairs. Unpacking a key into two variables fails:

scores = {"alice": 90, "bob": 85}
 
# ❌ iterates keys → "alice" unpacks into k, v → too many values
for k, v in scores:
    ...
 
# ✅ iterate key-value pairs
for k, v in scores.items():
    print(k, v)

Cause 2: str.split() produced more parts than expected

Text with an unexpected extra separator splits into too many pieces:

line = "key: value: with: colons"
 
# ❌ splits into 4 parts → too many values
key, value = line.split(":")
 
# ✅ split only on the first colon — value keeps the rest
key, value = line.split(":", 1)      # maxsplit=1
 
# ✅ or collect the tail into a list
key, *values = line.split(":")

• split(":", 1) → at most 2 parts, so 2 targets always fit.
• key, *values → values absorbs everything after the first part.

This is the top cause when parsing CSV lines, log entries, or KEY=VALUE config.

Cause 3: A function returns a different number of values

def get_point():
    return (1, 2, 3)     # returns 3 values
 
# ❌ x, y = get_point() → too many values
x, y = get_point()
 
# ✅ match the count
x, y, z = get_point()
 
# ✅ or take the first two, ignore the rest
x, y, *_ = get_point()

Check the function's actual return with print(get_point()). A refactor that adds a return value is a common trigger.

Cause 4: A list whose rows aren't length-2

pairs = [(1, 2), (3, 4, 5)]     # one row has 3 items
 
# ❌ blows up on the second row
for a, b in pairs:
    ...

Inspect the shape before trusting it:

for row in pairs:
    print(len(row), row)         # find the odd row out

Then fix the data, or use a, b, *rest = row if extra columns are legitimate.

Star-Unpacking: The General Fix

The * target absorbs any number of items, so counts never mismatch:

first, *middle, last = [1, 2, 3, 4, 5]
# first=1, middle=[2, 3, 4], last=5
 
head, *tail = "a,b,c,d".split(",")
# head="a", tail=["b", "c", "d"]
 
a, b, *_ = get_row()             # keep two, discard the rest

• Exactly one starred target is allowed per assignment.
• The starred variable always becomes a list (possibly empty).

Real Production Scenarios

Reproduce and Debug

The fastest debug is to print the count and value before the unpacking line:

value = get_something()
print(type(value), len(value), value)    # how many items, really?
a, b = value

len(value) tells you immediately whether the right-hand side matches your two targets. If value is a string, remember len counts characters — a frequent surprise when a function returns a string instead of a tuple.

Verification Steps

1. The counts match: len(right_hand_side) equals the number of targets (or you used a * target).
2. Dict loops use .items(); the loop runs without error.
3. Splits that can contain the separator use maxsplit or a starred target.
4. Functions return exactly what you unpack (or you absorb extras with *_).
5. No row in an iterable has an unexpected length.

Prevention

• Iterate dicts with .items() (or .keys() / .values() explicitly).
• Use str.split(sep, maxsplit) whenever the separator can appear in the data.
• Reach for a, b, *rest when length can vary.
• Print len() and the value when a shape is uncertain.
• Keep function return arity stable, or unpack with *_.
• Validate row lengths when parsing external data (CSV, logs).

Troubleshooting Matrix

Related Guides

• Fix AttributeError: 'DataFrame' object has no attribute 'append' after Pandas 2.0
• Fix ModuleNotFoundError: No module named 'dotenv'
• Fix ImportError: cannot import name 'Mapping' from 'collections'
• Fix TypeError: Object of type datetime is not JSON serializable
• Python iterables, iterators, and unpacking explained

External References

• Python — Tuples and sequences (unpacking)
• Python — Starred (extended) unpacking, PEP 3132
• Python — dict.items()
• Python — str.split()

FAQs

Can I use two starred targets to fix it? No. Only one starred target is allowed per assignment — a, *b, *c = x is a SyntaxError, because Python couldn't decide how to divide the extras. Use a single * and slice further if needed.

Does unpacking work on any iterable? Yes — tuples, lists, strings, generators, sets, and more. That generality is why a string unpacks into characters, which surprises people iterating dict keys. The count rule applies to all of them.

Why does a, b = "hi" work but a, b = "hey" fail? "hi" has exactly two characters, so it unpacks into a="h", b="i". "hey" has three, so it's too many values. Strings are iterables of characters.

Is *_ different from *rest? Only by convention. _ signals "I'm ignoring this," but it's still a real list. *rest keeps the extras for use. Both are valid single starred targets.

How do I unpack nested structures? Mirror the structure on the left: (a, b), c = ((1, 2), 3). Each level's counts must match, so a nested mismatch raises the same error at that level.