Skip to main content

How to Resolve Python Error "TypeError: not all arguments converted during string formatting"

The TypeError: not all arguments converted during string formatting is a common Python error typically associated with the older C-style string formatting operator (%). It signals a mismatch between the format specifiers in the string (like %s, %d, %f) and the type or number of arguments provided on the right side of the % operator. This often happens when accidentally mixing types (like string and number) or providing the wrong structure for multiple arguments.

This guide explains the causes related to the % operator and provides solutions, including recommending modern formatting methods.

Understanding the Error: The % Formatting Operator​

Python's % operator has two distinct meanings based on the types of its operands:

  • Modulo Operator: When both operands are numbers (e.g., 10 % 3), it calculates the remainder of the division.
  • String Formatting Operator: When the left operand is a string, Python interprets % as the start of a formatting operation. The string can contain format specifiers (like %s for string, %d for integer, %f for float), and Python expects corresponding values on the right side to substitute into those specifiers.

The TypeError: not all arguments converted during string formatting occurs when Python attempts the string formatting operation (because the left operand is a string) but finds that the argument(s) on the right side don't match the type or structure expected by the format specifiers within the string.

Cause 1: Using % Operator with Incompatible Types (String and Number)​

This often happens when you intend to perform the mathematical modulo operation but one of the operands is mistakenly a string. Python defaults to the string formatting interpretation because the left operand is a string, but then fails because the right operand (a number) doesn't fit the expected formatting structure (often expecting a tuple or mapping if format specifiers were present, or causing type mismatches if they were).

Error Scenario

value_str = "100" # This is a string
divisor = 7

try:
    # ⛔️ TypeError: not all arguments converted during string formatting
    # Python sees 'str % int'. It tries string formatting, expecting format codes
    # in the string that match the integer, but finds none or incompatible ones.
    remainder = value_str % divisor
    print(remainder)
except TypeError as e:
    print(e)

Solution 1: Convert Types for Intended Operation​

Check what operation you actually intended.

Convert String to Number for Modulo Arithmetic​

If you meant to calculate the remainder, convert the string to an integer (int()) or float (float()) before using the % operator.

value_str = "100"
divisor = 7

# ✅ Convert string to integer for math modulo
try:
    remainder = int(value_str) % divisor
    print(f"Remainder ({value_str} % {divisor}): {remainder}") # Output: 2
except ValueError:
    print(f"Cannot convert '{value_str}' to an integer.")

Convert Number to String for % Formatting​

If you intended to format the number into the string using the old % style (less common now, but possible), ensure the string has appropriate format specifiers and convert the number using %s or the correct numeric specifier.

count = 50

# ✅ Use %s (string representation) or %d (integer) specifier
message_s = "Count: %s items" % str(count)  # Explicit str() conversion works
message_d = "Count: %d items" % count       # %d handles the integer directly

print(message_s) # Output: Count: 50 items
print(message_d) # Output: Count: 50 items

Cause 2: Incorrect Argument Structure for % Formatting​

When using old-style % formatting with multiple specifiers in the string, Python expects the arguments on the right side to be provided within a tuple (for positional formatting) or a mapping (dictionary) (for named formatting). Providing a single value or the wrong type of collection will cause the error.

Error Scenario

format_string = "Name: %s, Age: %d"
name = "Alice"
age = 30

try:
    # ⛔️ TypeError: not all arguments converted during string formatting
    # Needs a tuple (name, age) on the right, not just 'name'
    result = format_string % name
except TypeError as e:
    print(f"Error 1: {e}")

try:
    # ⛔️ TypeError: must be mapping, not list
    # If using named specifiers, need a dict, not list/tuple
    result_named = "Value: %(val)d" % [123]
except TypeError as e:
     print(f"Error 2: {e}")

Solution 2: Use Correct Tuple/Mapping for Multiple Arguments​

  • For multiple specifiers: Wrap the arguments on the right side in a tuple. 
    format_string = "Name: %s, Age: %d"
    name = "Alice"
    age = 30

    # ✅ Provide arguments as a tuple
    result = format_string % (name, age)
    print(result) # Output: Name: Alice, Age: 30
  • For named specifiers: Provide a dictionary on the right side. 
    format_string_named = "Item: %(item)s, Price: $%(price).2f"
    data = {'item': 'Widget', 'price': 19.99}

    # ✅ Provide arguments as a dictionary
    result_named = format_string_named % data
    print(result_named) # Output: Item: Widget, Price: $19.99

The % operator for string formatting is largely considered outdated. Modern Python heavily favors str.format() and especially f-strings for their clarity, flexibility, and reduced potential for errors like this one.

Using str.format()​

This method uses {} placeholders and a .format() method call. It handles type conversions more gracefully in many cases (though you still need the correct number of arguments, usually causing IndexError or KeyError if mismatched, not this specific TypeError).

first = "Tom"
age = 42
cost = 15.75

# Positional placeholders
result_pos = "User: {}, Age: {}, Cost: {:.2f}".format(first, age, cost)
print(result_pos) # Output: User: Tom, Age: 42, Cost: 15.75

# Named placeholders
result_named = "User: {name}, Age: {user_age}".format(name=first, user_age=age)
print(result_named) # Output: User: Tom, Age: 42

Using f-strings (Python 3.6+)​

f-strings (formatted string literals) are the most current and often most readable method. They allow embedding expressions directly and handle basic type conversions automatically.

first = "Charlie"
age = 25
cost = 9.99

# ✅ F-string handles types automatically within the braces
result_f = f"User: {first}, Age: {age}, Cost: ${cost:.2f}"
print(result_f) # Output: User: Charlie, Age: 25, Cost: $9.99
note

Using f-strings completely avoids the % operator ambiguity and the "not all arguments converted" TypeError.

Debugging the Error (type())​

If you get this TypeError with the % operator:

  1. Check the type of the left operand: print(type(left_operand)). It must be a string for formatting to be attempted.
  2. Check the type of the right operand: print(type(right_operand)).
  3. If Math Was Intended: Ensure both operands are numeric (int or float). Convert strings using int() or float().
  4. If Formatting Was Intended: Ensure the format specifiers in the string match the type of the argument(s) on the right. If there are multiple specifiers, ensure the right side is a tuple or dictionary as required.

Conclusion​

The TypeError: not all arguments converted during string formatting primarily occurs when using the older % string formatting operator with mismatched arguments:

  1. Trying to use % for math (modulo) when one operand is a string. Fix: Convert the string to int or float first (int(my_str) % num).
  2. Using % formatting with incorrect argument types or structure (e.g., providing a single number when a tuple is needed for multiple %s / %d specifiers). Fix: Provide arguments in a tuple ("..." % (arg1, arg2)) or use correct specifiers.

The strongly recommended solution is to migrate away from % formatting and use modern Python techniques:

  • f-strings (f"..."): Most readable and efficient (Python 3.6+).
  • str.format(): More versatile than %, less prone to this specific TypeError.

By understanding the cause related to the % operator and adopting modern formatting, you can prevent this error and write clearer Python code.

Table of Contents