Introduction

This Python error means a piece of code expected text as str, but you passed binary data as bytes instead. In Python 3, text and bytes are intentionally different types, so the fix is not "force them together" but to decide whether the code should operate on decoded text or raw binary data.

Understand The str Versus bytes Split

In Python 3:

• 'str represents text'
• 'bytes represents raw binary data'

Example:

1text = "hello"
2raw = b"hello"
3
4print(type(text))
5print(type(raw))

Even though they look similar, Python does not treat them as interchangeable. That is why an operation designed for text can raise:

TypeError: must be str, not bytes

A Common Case: Writing Bytes To A Text File

This fails:

1data = b"hello"
2
3with open("example.txt", "w") as file:
4    file.write(data)

The file was opened in text mode, so write() expects str.

Fix it by decoding:

1data = b"hello"
2
3with open("example.txt", "w", encoding="utf-8") as file:
4    file.write(data.decode("utf-8"))

Or keep everything binary and open the file in binary mode:

1data = b"hello"
2
3with open("example.bin", "wb") as file:
4    file.write(data)

The right choice depends on whether the content is text or binary.

Another Common Case: Mixing Bytes Into String Operations

This also fails:

1prefix = "User: "
2name = b"Ada"
3
4print(prefix + name)

You cannot concatenate str and bytes.

Fix it by decoding the bytes:

1prefix = "User: "
2name = b"Ada"
3
4print(prefix + name.decode("utf-8"))

Or keep the entire operation in bytes if you really want binary output:

1prefix = b"User: "
2name = b"Ada"
3
4print(prefix + name)

Consistency is the real rule.

Network And Subprocess Code Often Produces Bytes

Sockets, subprocess output, and many low-level APIs return bytes by default.

Example:

1import subprocess
2
3result = subprocess.run(
4    ["echo", "hello"],
5    capture_output=True
6)
7
8print(result.stdout)
9print(result.stdout.decode("utf-8").strip())

If you treat result.stdout as ordinary text without decoding it first, string operations may raise the error.

That is why it helps to know where bytes naturally enter the program.

Decode Early Or Stay Binary Intentionally

A good design rule is to pick one of these paths:

1. decode bytes into text near the boundary and work with str afterward
2. keep the pipeline binary all the way through until text is actually needed

What causes bugs is drifting back and forth without deciding.

For example, HTTP libraries, file uploads, or encrypted payloads often belong in bytes for a while. User-facing display and text parsing belong in strings.

Encoding Must Match Reality

Decoding only works if you choose the correct encoding:

payload = "cafe".encode("utf-8")
print(payload.decode("utf-8"))

If the bytes are not UTF-8 but you decode them as UTF-8 anyway, you may get a UnicodeDecodeError instead of the original TypeError.

So the deeper fix is not merely "call decode." It is "decode with the encoding the bytes were actually created with."

Common Pitfalls

The biggest mistake is blindly sprinkling .decode() or .encode() around the code without deciding which layer should own the conversion.

Another mistake is opening files in text mode and then writing bytes, or opening them in binary mode and then writing strings.

People also forget that many APIs return bytes by default, especially network and subprocess functions, so later string operations fail unexpectedly.

Finally, decoding with the wrong encoding may replace one bug with another. Always know where the bytes came from and what encoding they use.

Summary

• The error means Python expected str but received bytes.
• 'str is text and bytes is raw binary data in Python 3.'
• Decode bytes when the program should operate on text.
• Keep data binary when the content is not yet text and use binary file or stream APIs.
• The cleanest fix is to handle text-versus-binary boundaries deliberately instead of mixing the two types accidentally.