ValueError

                ValueError(message)
              

Purpose

ValueError signals that a value has the right type but the wrong content for what’s being asked of it — int("abc") raises it because a string is a perfectly valid argument type for int() in general, but "abc" specifically doesn’t represent a number.

Example

int("abc")               # ValueError: invalid literal for int() with base 10: 'abc'
[1, 2, 3].index(99)      # ValueError: 99 is not in list

def set_age(age: int) -> None:
    if age < 0:
        raise ValueError(f"age cannot be negative, got {age}")

Behavior notes

• Contrast with TypeError, which signals the argument’s type itself was wrong (int(None), passing a list where a function expects a str). ValueError means the type was fine but the specific value wasn’t acceptable.
• Raising ValueError with a specific, descriptive message (as set_age does above) is the standard way to reject an invalid argument in your own functions — it’s a real validation tool, not just something the standard library raises at you.
• A caller that wants to handle an invalid value gracefully catches ValueError specifically (except ValueError:), rather than a bare except: that would also swallow unrelated bugs.

Common mistakes

• Raising a bare Exception (or returning None, or printing an error and continuing) instead of a specific, catchable exception type like ValueError — it works, in the sense that the program doesn’t crash, but it makes deliberate error handling by a caller much harder.
• Catching ValueError far too broadly — around a large block of code instead of just the one call that might raise it — which can mask a ValueError coming from somewhere unexpected as if it were the one being handled.

Implementation notes

ValueError and its distinction from TypeError are part of the standard library’s exception hierarchy — defined by the language, identical across conforming implementations.