Python ValueError: What It Means and How to Fix It

Python halts with a ValueError:

ValueError: invalid literal for int() with base 10: '12a'

A ValueError is subtly different from a TypeError. The type is fine — you gave int() a string, which is exactly what it wants — but the value inside makes no sense for the operation. '12a' is a string, but it isn't a number. Here are the everyday cases.

'invalid literal for int()' — converting non-numeric text

n = int("12a")          # ❌ not a valid integer
age = int(input("Age: "))   # ❌ ValueError if the user types "twenty"

int() and float() need text that is actually a number. Guard user input with try/except:

raw = input("Age: ")
try:
    age = int(raw)
except ValueError:
    print("Please enter a whole number.")

Note int("3.5") also fails — that's a float literal, not an int. Use int(float("3.5")) if you want truncation.

'not enough values to unpack' / 'too many values to unpack'

The number of variables doesn't match the number of items:

a, b = [1, 2, 3]        # ❌ too many values to unpack (expected 2)
x, y = "hi", 

Match them, or use a starred catch-all:

a, b, *rest = [1, 2, 3]   # a=1, b=2, rest=[3]

This one bites hard when you split a line that doesn't have the expected number of fields: name, age = line.split(",") explodes on any row without exactly one comma.

'substring not found' — str.index()

"hello".index("z")       # ❌ ValueError: substring not found

.index() raises if the item isn't there. If a "not found" result is normal, use .find() (returns -1) or check with in first:

if "z" in text:
    i = text.index("z")

The list equivalent: list.index(x) and list.remove(x) both raise ValueError when x isn't present.

'math domain error'

import math
math.sqrt(-1)            # ❌ ValueError: math domain error

The value is outside the function's valid domain (a negative to sqrt, zero to log). Validate the input, or use cmath for complex results.

How to read it

The message quotes the exact offending value ('12a') — that's your clue. Trace it back: where did that value come from? Almost always it's external input (a file line, a form field, an API field) that didn't look the way you assumed.

The checklist

1. invalid literal for int() → validate/convert input inside try/except ValueError.
2. unpack errors → the item count must match the variable count (or use *rest).
3. .index()/.remove() "not found" → check with in first, or use .find().
4. math domain error → the value is out of range; validate before calling.
5. The quoted value in the message tells you exactly what came in wrong — trace its source.

Frequently Asked Questions

What's the difference between ValueError and TypeError?

TypeError means the type was wrong (adding a str to an int). ValueError means the type was right but the value was invalid for the operation — like int("abc"), where a string is expected but that particular string isn't a number.

How do I stop int(input()) from crashing on bad input?

Wrap it in try/except ValueError and re-prompt or show a message. int() raises ValueError on anything that isn't a valid integer string, and user input is a common source.

Why does 'a, b = my_list' raise ValueError?

Because my_list doesn't have exactly two items. Unpacking requires the variable count to match the item count. Use a, b, *rest = my_list to absorb extras, or check the length first.