This error occurs in Python when a string formatted with the % operator expects more values than are supplied, or when the number of placeholders doesn't match the number of arguments passed.
The % formatting syntax, also known as printf-style formatting, uses placeholders like %s, %d, or %f to insert values into strings. When the number of placeholders exceeds the number of provided values, Python raises a TypeError with the message "not all arguments converted during string formatting." This typically happens due to a mismatch between expected and actual arguments.
For example, if you write "Hello %s, your score is %d" % ("Alice",), Python throws the error because two placeholders (%s and %d) are used but only one value is provided. The correct version requires two values: "Hello %s, your score is %d" % ("Alice", 95).
Python's % formatting evaluates the left side of the % operator as a format string and the right side as a tuple of values. Each placeholder in the string maps to one element in the tuple. If the tuple is shorter than the number of placeholders, Python cannot complete the substitution and raises the error.
Placeholders have specific type codes: %s for strings, %d for integers, %f for floats. Using the wrong type code can cause silent failures or unexpected behavior, especially with mixed types. For example, passing a float to a %d placeholder may result in truncation, but the error won't trigger unless the count is off.
When debugging, inspect both the format string and the argument list. A common mistake is forgetting to wrap single values in a tuple using parentheses. Writing "%s" % "John" works, but "%s %s" % "John" fails because "John" is a string, not a tuple. The correct form is "%s %s" % ("John", "Doe").
The most frequent cause is omitting a required argument. For instance:
print("User %s logged in at %s" % ("admin"))
This produces the error because two placeholders exist but only one value is passed. Fix it by adding the missing time value: "User %s logged in at %s" % ("admin", "14:30").
Another issue arises when using variables incorrectly. Suppose you define:
name = "Bob"
score = 87
print("Result: %s, Score: %d" % (name, score))
This works. But if you accidentally pass only one variable as a tuple:
print("Result: %s, Score: %d" % (name,))
Now only one value is passed, so the error appears. Always ensure the tuple contains the correct number of elements.
A subtle problem occurs with nested formatting. Consider:
template = "Processing %d records: %s%% complete"
print(template % (100, "95"))
Here, the %% escapes the percent sign. The format string expects two values: an integer and a string. If you pass only one, the error triggers. The correct call is template % (100, "95").
While the error message is consistent, the root causes differ based on context. Below are the main categories:
| Issue Type | Root Cause | Fix |
|---|---|---|
| Missing argument | Too few values in the argument tuple | Add missing values or verify argument count |
| Incorrect tuple structure | Single value passed without wrapping in tuple | Use parentheses: (value,) |
| Type mismatch | Wrong type code for value (e.g., %d for float) | Use %f for floats, %s for strings |
| Escaping errors | Percent signs not escaped with %% | Use %% to display a literal % |
One non-obvious point: Python treats a single string as a sequence of characters. So "%s" % "A" works, but "%s %s" % "AB" fails because "AB" is treated as two characters, not two values. The correct way is "%s %s" % ("A", "B").
This error commonly surfaces in logging, file output, and user-facing messages. For example, in a web application, a log line like:
logger.info("Request from %s failed with status %d" % (user_id, status))
Will fail if status is missing or if user_id is passed as a string without proper tuple handling.
It also appears in scripts that parse configuration files or process CSV data. A script reading a row and formatting a message:
row = ["John", "2023-04-01"]
message = "User %s joined on %s" % row
fails if the row list is incomplete. The fix is to validate input length before formatting.
Using f-strings (introduced in Python 3.6) avoids this entirely. The equivalent code:
message = f"User {row[0]} joined on {row[1]}"
is safer and less error-prone. However, legacy codebases still rely on % formatting, making this error relevant in maintenance work.
Developers often mistake this error for a syntax error or a missing import. The error message is precise: "not all arguments converted during string formatting" - it's a runtime type error, not a parsing failure.
It's also frequently mistaken for issues with string encoding or Unicode. But the error occurs regardless of encoding. The problem lies in argument count, not character representation.
Another confusion: some assume the error means the string itself is invalid. But the string is valid; it's the argument list that's incomplete. The format string "%s %d" is syntactically correct. The error only triggers when the argument list doesn't match.
I encountered this error while processing a batch of user registration logs. The original code was:
for record in logs:
print("New user: %s, ID: %d" % (record['username']))
Running it produced:
TypeError: not all arguments converted during string formatting
After reviewing, I realized the record dictionary had a 'user_id' field, but it wasn't included in the argument list. The fix was:
for record in logs:
print("New user: %s, ID: %d" % (record['username'], record['user_id']))
Adding the missing record['user_id'] resolved the error. The script ran correctly after that.
Since then, I've adopted a habit of validating argument counts before running string formatting, especially in loops or functions that process changing data.
Always verify that the number of placeholders matches the number of values. Use tuples explicitly: (arg1, arg2), not arg1, arg2 without parentheses.
Consider migrating from % formatting to f-strings. They're more readable and less prone to this class of error. For example:
name = "Alice"
score = 95
result = f"Hello {name}, your score is {score}"
is clearer and safer than the % version.
If you must use % formatting, test with known inputs. Use assertions to catch mismatches early:
assert len(args) == num_placeholders, f"Expected {num_placeholders} args, got {len(args)}"
Finally, remember: the error is not about the string being malformed. It's about the argument list being too short. Check both sides of the % operator.