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.

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:
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:
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.
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:
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:
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:
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.
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:
def process(value):
if not isinstance(value, int):
raise ValueError(f"Expected int, got {type(value).__name__}")
return value * 2While 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.
def process(value: int) -> int:
return value * 2Type 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.
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:
import logging
logger = logging.getLogger(__name__)
try:
process(data)
except TypeError as exc:
logger.error("TypeError processing data: %s", exc, exc_info=True)
raiseRe-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
Noneor 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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.