🚨 Python Error Guide: 'TypeError: can only concatenate str (not "int") to str' — Cause, Fix, and Troubleshooting Guide

Overview

Python raises this when you use + to join a string and a non-string:

TypeError: can only concatenate str (not "int") to str

Python 3 refuses to guess how to combine different types with +. "count: " + 5 is ambiguous — do you mean the text "count: 5" or some arithmetic? Rather than silently coerce (as some languages do), it raises. The variant names the offending type ("int", "NoneType", "list"). The fix is to make the types match: convert the number with str(), or better, build the string with an f-string so conversion is automatic.

Symptoms

• The message follows the pattern can only concatenate str (not "<type>") to str.
• It fires on a line building a message, path, SQL, or log line with +.
• The reverse form — TypeError: unsupported operand type(s) for +: 'int' and 'str' — appears when the number is on the left.
• A value you thought was a string turns out to be an int, None, or a list.

Common Root Causes

• Concatenating a number into text — "port " + 8080.
• A variable is a different type than assumed — a config value parsed as int, or a function returning None.
• Number-on-the-left form — year + " report" gives unsupported operand type(s) for +: 'int' and 'str'.
• Joining a list or bytes to a string with +.
• Building paths/URLs by +-ing an integer ID into a string.
• Off-by-one type confusion after json.load/int() where a field is numeric.

Diagnostic Workflow

Print the type of each operand at the failing line:

print(type(prefix), type(value))   # <class 'str'> <class 'int'>

Reproduce minimally to see which side is wrong:

"count: " + 5      # TypeError: can only concatenate str (not "int") to str
5 + " apples"      # TypeError: unsupported operand type(s) for +: 'int' and 'str'

Check where the value came from — int(), json.load, or a function that can return None.

Example Root Cause Analysis

A script built a status message:

retries = int(os.environ.get("RETRIES", "3"))
msg = "giving up after " + retries + " retries"

It failed:

TypeError: can only concatenate str (not "int") to str

retries came from int(...), so it was an integer, and + can’t join it to the surrounding strings. Three clean fixes, best first:

# f-string (clearest, auto-converts)
msg = f"giving up after {retries} retries"

# explicit str()
msg = "giving up after " + str(retries) + " retries"

# str.format
msg = "giving up after {} retries".format(retries)

The f-string is preferred: it handles the conversion, reads naturally, and avoids the fragile + chain entirely. For number-heavy output you can even format inline, e.g. f"{ratio:.1%}".

Prevention Best Practices

• Prefer f-strings — f"{x}" converts any value to its string form automatically; no + needed.
• Convert explicitly with str() when you must use + with mixed types.
• Keep types consistent — don’t let a variable be sometimes a str and sometimes an int; decide at the boundary.
• Use "".join(...) for joining many strings (and convert elements first) rather than long + chains.
• Guard values that can be None — f"{x or 'n/a'}" avoids the NoneType variant.
• Enable a type checker (mypy, Pyright) to catch str/int mixing before runtime.

Quick Command Reference

f"count: {n}"                     # f-string: auto str conversion (preferred)
"count: " + str(n)                # explicit conversion for + concatenation
"{} of {}".format(done, total)    # str.format alternative
", ".join(str(x) for x in items)  # join a sequence, converting each element
f"{ratio:.1%}"                    # inline numeric formatting
print(type(a), type(b))           # diagnose which operand is non-str

Related Guides

• Bash & Python Error Guide: ‘TypeError: NoneType object is not subscriptable’ — a related TypeError from an unexpected None value.
• Python Error Guide: ‘ValueError: invalid literal for int() with base 10’ — the conversion error that often produces the int you then mis-concatenate.
• Python Error Guide: ‘KeyError’ — another common data-handling error in the same scripts.

Conclusion

TypeError: can only concatenate str (not "int") to str is Python 3 refusing to guess how to + a string and a number. Convert the non-string with str(), or — cleaner and less error-prone — build the text with an f-string that converts automatically. Keep each variable a consistent type at its boundary and enable a type checker, and this whole class of string-building TypeErrors stops appearing in your scripts.