Handling Python Type Conversion Errors

Python type conversion errors typically surface as TypeError or ValueError when you try to turn data from one type into another in a way the runtime cannot handle. The most familiar case is calling int("abc"), which raises ValueError because the string is not a valid integer. But conversion errors also appear in less obvious places: when a function receives an unexpected type, when a custom object lacks the required conversion method, or when a container conversion silently changes the data structure. Understanding the distinction between TypeError and ValueError is the first step to resolving them.

The Difference Between TypeError and ValueError

TypeError occurs when the operation is not supported for the given types. For example, int("123") is valid, but int(None) raises TypeError because None is not a string, bytes, or number. ValueError occurs when the operation is supported but the value is inappropriate. int("12.5") raises ValueError because the string contains a decimal point, even though it is a string. Knowing which exception you are dealing with tells you whether the problem is the type of the input or its content.

# TypeError: int() argument must be a string, a bytes-like object or a number, not 'NoneType'
# int(None)

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

When you catch these exceptions, you need to handle them differently. TypeError often indicates a programming mistake that should be fixed at the call site, while ValueError may represent invalid user input that you need to validate or fall back on.

Converting Strings to Numbers: The Most Common Failure

Converting user input from a form, CLI argument, or environment variable to an integer or float is where conversion errors happen most frequently. The input is always a string, and the string may not match the expected numeric format.

def parse_port(raw: str) -> int:
    try:
        return int(raw)
    except ValueError:
n        raise ValueError(f"Invalid port number: {raw}") from None

This pattern works, but it only catches ValueError. If raw is None or an integer, int() may raise TypeError. A robust conversion function should check the type first or catch both exceptions.

def safe_int(value):
    if isinstance(value, int):
        return value
    if isinstance(value, str):
        try:
            return int(value)
        except ValueError:
            return None
    return None

Using isinstance before conversion avoids the TypeError and lets you handle ValueError separately. This pattern is useful when you cannot guarantee the input type, such as when reading from a configuration file that may contain numbers as strings or native types.

Converting Between Containers: List, Tuple, Set, and Dictionary

Container conversions rarely raise exceptions, but they can produce surprising results. Converting a list to a set removes duplicates and loses order, which may be unintended. Converting a dictionary to a list yields a list of keys, not key-value pairs. These are not errors in the Python sense, but they are logical errors that stem from assuming the conversion does something else.

pairs = {"a": 1, "b": 2}
list(pairs)  # ['a', 'b']
list(pairs.items())  # [('a', 1), ('b', 2)]

A true conversion error occurs when you try to convert a list to a dictionary. dict([1, 2]) raises TypeError because each element must be a key-value pair. Similarly, converting a set of lists to a set raises TypeError because lists are unhashable.

# TypeError: unhashable type: 'list'
# set([[1, 2], [3, 4]])

When you need to convert a nested structure, check the element types first. If you are building a set of tuples from a list of lists, convert each inner list to a tuple explicitly.

list_of_lists = [[1, 2], [3, 4]]
set_of_tuples = {tuple(item) for item in list_of_lists}

Type Conversion in Function Arguments and API Boundaries

When you write a function that accepts multiple types, conversion errors often occur at the boundary between your code and external input. For example, a function that accepts either a path as a string or a Path object may need to convert both to Path internally. If you call Path on an integer, you get a TypeError.

from pathlib import Path

def process_path(path):
    if isinstance(path, (str, Path)):
        path = Path(path)
    else:
        raise TypeError("path must be a string or Path")
    return path.resolve()

Explicit type checks at the boundary make the failure point clear. They also prevent confusing errors deep inside the function. When you accept a value that can be a number or a numeric string, you can use a helper that attempts conversion and falls back to the original value.

def coerce_number(value):
    if isinstance(value, (int, float)):
        return value
    if isinstance(value, str):
        try:
            return int(value)
        except ValueError:
            try:
                return float(value)
            except ValueError:
                return value
    return value

This pattern is common in configuration parsers and CLI tools where environment variables are always strings but may represent numbers.

Performance and Maintainability of Conversion Code

Repeatedly converting the same value in a loop can waste CPU cycles. If you parse a string to an integer once and then use it many times, store the converted value instead of converting on every access. This is a performance concern, but it is also a maintainability one: a single conversion point makes the code easier to reason about.

# Inefficient: converts on every iteration
for item in items:
    if int(item) > 10:
        pass

# Better: convert once
for item in items:
    numeric = int(item)
    if numeric > 10:
        pass

Using try/except for control flow is acceptable in Python, but it can hide logic if overused. If you find yourself catching ValueError in many places, consider writing a small conversion helper that returns a default or raises a domain-specific exception. This centralizes error handling and makes the code easier to test.

Edge Cases: None, Empty Strings, and Custom Conversion Methods

Conversion errors often occur with edge values that are technically valid types but have unexpected content. int("") raises ValueError, as does float(" "). bool("False") returns True because any non-empty string is truthy. These behaviors are consistent but can surprise developers who expect a more literal conversion.

Custom objects can define __int__, __float__, or __str__ to control how they are converted. If a class defines __int__, calling int(obj) will use that method. If the method raises ValueError, the conversion fails. If the method is missing, Python raises TypeError.

class Temperature:
    def __init__(self, celsius):
        self.celsius = celsius

    def __int__(self):
        return int(self.celsius)

    def __float__(self):
        return float(self.celsius)

When you write conversion functions for user-defined types, test both the presence of the method and the range of values it accepts. A custom __int__ that returns a float will raise TypeError because int() expects an integer.

Building a Robust Conversion Layer

Instead of scattering try/except blocks across your codebase, you can build a small conversion utility that handles common cases and produces consistent error messages. This is especially useful for APIs that accept multiple input formats.

def to_int(value, default=None):
    if isinstance(value, int):
        return value
    if isinstance(value, float):
        return int(value)  # truncates, not rounds
    if isinstance(value, str):
        try:
            return int(value)
        except ValueError:
            return default
    return default

This function covers the most common conversion paths and returns a default instead of raising. You can extend it to handle booleans, bytes, or custom objects by adding branches. The key is to decide early whether you want to raise or return a fallback. For user input, a fallback is often safer; for internal data, raising early may be better.

When you do raise, use raise ... from None to suppress the chained exception context if you are re-raising a new exception. This keeps the traceback clean and focuses on the actual error.

def parse_config_value(raw):
    try:
        return int(raw)
    except ValueError as exc:
        raise ValueError(f"Invalid integer in config: {raw}") from None

By centralizing conversion logic, you reduce the chance of inconsistent error handling and make it easier to add new types later. The tradeoff is that you must keep the helper up to date as your data formats evolve, but that is a small cost compared to debugging scattered conversion failures.