When does Python raise ValueError rather than TypeError?

## The contract carried by a name Python's built-in exception names are not decoration; each one promises something specific about the cause, and a caller writes handlers against that promise. The two most confused are `TypeError` and `ValueError`, and the distinction is genuinely simple once stated: **`TypeError` is about the kind of object, `ValueError` is about its content.** `TypeError` means the operation could not even be attempted on an object of that type. The argument is a list where a number or string was required, a non-callable was called, an unhashable object was used as a dict key, two incompatible types were added, or a function was called with the wrong number of positional arguments or an unexpected keyword. `ValueError` means the type was right, the operation was genuinely attempted, and this particular value cannot be handled. Parsing `'twelve'` as an integer, asking for the square root of a negative number, unpacking a three-element sequence into two names, or passing an out-of-range value to a constructor all raise it. ```python def to_count(raw): try: return int(raw) except ValueError: return 0 except TypeError: raise ``` That shape is the point of the distinction. Bad *content* from an untrusted source is often recoverable — substitute a default, skip the record, ask again. A bad *type* is nearly always a bug in the calling code, so it is left to propagate. Collapsing both into one handler throws away that signal. ## The rest of the family The same discipline runs through the whole built-in tree, and matching by class makes the intermediate nodes useful: * **`LookupError`** is the parent of `KeyError` and `IndexError`. A `KeyError` says a mapping had no such key; an `IndexError` says a sequence index was out of range. Code that walks a nested structure of mixed dicts and lists can catch `LookupError` once and cover both. * **`ArithmeticError`** is the parent of `ZeroDivisionError`, `OverflowError` and `FloatingPointError`. * **`AttributeError`** means the attribute lookup failed on that object; **`NameError`** means no such name was bound in any enclosing scope. `UnboundLocalError` is a `NameError` subclass, raised when a local name is read before assignment. * **`UnicodeDecodeError`** and `UnicodeEncodeError` derive from `UnicodeError`, which derives from `ValueError` — which is exactly right, since the bytes were of the correct type but not decodable under that codec. A handler naming `ValueError` catches them. * **`StopIteration`** is not an error condition at all; it is the protocol signal that an iterator is exhausted. * **`RuntimeError`** is the honest fallback for "something went wrong that no other built-in describes". `RecursionError` derives from it. ## Reading the name as a diagnosis Because the names are contracts, a traceback's final line is already a diagnosis. `KeyError: 'source_lang'` says a mapping was missing a key, and names it. `TypeError: unsupported operand type(s) for +: 'int' and 'str'` says two values of incompatible kinds met — usually a missing conversion at a boundary. `ValueError: invalid literal for int() with base 10: 'twelve'` says the parse was attempted on a real string and failed. Reading the class before reading the message is the fastest triage step there is. ## When you raise one yourself The same promise binds code you write. If a function is handed an argument of the wrong kind and cannot proceed, `TypeError` is correct. If the argument is the right kind but out of range or unparseable, `ValueError` is correct. Reaching for `Exception` or `RuntimeError` when a precise built-in exists strips information from every caller downstream: they can no longer distinguish "my input was malformed" from "my code is wrong", and they end up matching on message text, which is fragile and untranslatable. A useful check when you are unsure: could the caller fix this by converting the argument, or only by supplying different content? Conversion means `TypeError`; different content means `ValueError`. And when neither built-in fits the meaning, that is the signal to reach for a more specific class rather than to misuse one of these two. ## A near-miss worth knowing Indexing a list out of range raises `IndexError`, but *slicing* one out of range raises nothing at all: `items[5:9]` on a three-element list simply returns an empty list. That asymmetry catches candidates who assume any out-of-range access fails loudly, and it illustrates the underlying idea — the exception classes describe what the operation promised, not merely what the numbers looked like. Indexing promises a specific element and cannot deliver; slicing promises a best-effort window and can. `dict.get` is the same idea from the other direction: it promises a default, so it has no `KeyError` to raise.