Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Understanding and Fixing Python TypeError

Python TypeError occurs when an operation or function is applied to an incompatible type. Learn how to read tracebacks and fix these runtime errors.

~4 min readPython
#Python#TypeError#Debugging#Exception Handling
Illustration of a Python error showing type mismatch between integer and string

A Python TypeError occurs when an operation or function is applied to an object of an inappropriate type. Unlike syntax errors, which are detected before the program runs, a TypeError is raised at runtime when the interpreter cannot reconcile the types involved. This article explains the common causes, how to diagnose them from tracebacks, and how to write code that avoids these failures.

What Actually Raises a TypeError

The Python interpreter raises a TypeError when an operation or function is used in a way that is not supported for the types involved, or when a function is called with arguments that do not match its signature. The most common triggers are:

  • Calling a non-callable object
  • Passing the wrong number of arguments to a function
  • Using an operator with incompatible operand types
  • Iterating over a non-iterable object
  • Indexing a sequence with a non-integer
  • Concatenating strings with non-strings

Consider this minimal example:

python
value = 42 print(value + " items")

Running this produces a traceback ending with TypeError: unsupported operand type(s) for +: 'int' and 'str'. The interpreter refuses to guess whether you intended to convert the integer to a string or the string to an integer. That explicitness is a core Python design principle.

Reading the Traceback Effectively

The traceback is your primary diagnostic tool. It shows the exact line where the error occurred and the call stack leading to it. The final line names the operation and the types involved. For example:

code
Traceback (most recent call last): File "example.py", line 3, in <module> result = 1 + "two" TypeError: unsupported operand type(s) for +: 'int' and 'str'

Here, the message tells you that the + operator cannot combine int and str. The file and line number point to the exact line that failed. When the error originates deeper in a call chain, the traceback shows each frame, allowing you to trace how the offending value arrived at that point.

Common Scenarios and Their Fixes

Wrong Argument Types

Functions often expect specific types. Passing a string where an integer is required, or vice versa, raises a TypeError when the function tries to use the value in an operation.

python
def repeat(text, times): return text * times repeat("a", "3")

The multiplication of a string by a string is not defined, producing TypeError: can't multiply sequence by non-int of type 'str'. The fix is to convert the argument explicitly:

python
repeat("a", int("3"))

Missing or Extra Arguments

Calling a function with the wrong number of arguments also raises a TypeError. The message states the expected and received counts:

python
def greet(name, greeting="Hello"): return f"{greeting}, {name}" greet("Alice", "Hi", "extra")

This produces TypeError: greet() takes from 1 to 2 positional arguments but 3 were given. Review the function signature and the call site to reconcile the mismatch.

Calling Non-Callable Objects

Attempting to call an integer, list, or other non-callable object yields TypeError: 'int' object is not callable. This often happens when a variable shadows a function name:

python
sum = 10 result = sum([1, 2, 3])

Here, sum is reassigned to an integer, so the subsequent call fails. Rename the variable or avoid shadowing built-in names.

Iterating Over Non-Iterables

Using a for loop on a non-iterable object raises a TypeError that names the offending type, such as 'int' object is not iterable. A common variation occurs when a function returns None instead of a list, and the caller tries to iterate over the result.

python
def get_items(flag): if flag: return [1, 2, 3] # Missing return statement implicitly returns None for item in get_items(False): print(item)

This snippet raises TypeError: 'NoneType' object is not iterable because the missing return statement makes the function return None. Fix by ensuring all code paths return an iterable, or by checking the return value before iterating.

Using isinstance and Type Hints to Prevent TypeErrors

Explicit type checks can catch problems early. The isinstance function lets you verify the type of an argument before performing an operation:

python
def process(value): if not isinstance(value, int): raise ValueError(f"Expected int, got {type(value).__name__}") return value * 2

While this raises a different exception, it gives a clearer error message than a cryptic TypeError. However, overusing isinstance can make code rigid. A more maintainable approach is to use type hints and static analysis tools like mypy to catch type mismatches before runtime.

python
def process(value: int) -> int: return value * 2

Type hints do not enforce types at runtime, but they enable static checking and improve code readability. Combined with a type checker in CI, type hints can catch many TypeError scenarios before deployment.

Handling TypeErrors Gracefully

Sometimes you cannot prevent a TypeError because the input comes from an external source. In that case, catch it explicitly and handle it according to your application's requirements.

python
try: result = value + " units" except TypeError: result = f"{value} units"

Be careful not to catch TypeError too broadly. Swallowing it without logging can hide real bugs. In production, log the traceback and the offending value to aid debugging:

python
import logging logger = logging.getLogger(__name__) try: process(data) except TypeError as exc: logger.error("TypeError processing data: %s", exc, exc_info=True) raise

Re-raising after logging preserves the original error and lets an upstream handler decide how to respond.

Production Considerations and Maintainability

TypeErrors often surface in production when data shapes change or integrations receive unexpected payloads. To minimize surprises:

  • Validate external input at the boundary, not deep inside business logic.
  • Use type hints and static analysis in your build pipeline.
  • Write unit tests that exercise edge cases, such as passing None or mismatched types.
  • Avoid catching TypeError in a way that masks programming errors; let them fail loudly in development.

A TypeError is a signal that your code's assumptions about types are violated. The sooner you identify and correct that assumption, the more robust your system becomes. By reading tracebacks carefully and applying defensive checks where appropriate, you can reduce the frequency of these runtime failures and make your codebase easier to maintain.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.