Fix Expected str, bytes or os.PathLike Object in Python

The error saying Python expected a str, bytes, or os.PathLike object usually means a file or path API received the wrong kind of value. The function wanted a path, but the caller passed file contents, a list, a dictionary, or another unrelated object. The fix is to trace the value at the failing call and pass a valid path representation.

Contents

Quick answer

Pass a string path such as "data/report.csv", a bytes path when the operating system interface requires it, or a pathlib.Path object. Do not pass the contents returned by open().read() where a filename is expected. Use os.fspath() at a boundary when a library needs a path-like value, and use type() or repr() to inspect the actual object.

The official Python os.PathLike documentation defines the protocol for objects that represent filesystem paths. pathlib is usually the clearest way to build paths because it preserves path operations as data instead of relying on string concatenation.

Python expected str bytes or os.PathLike error showing valid path inputs normalized by os.fspath — Pass a path object or path string, not file contents, a list, or an unrelated object.

Recognize the failing shape

Many APIs accept a filename but not the contents of that file. A common mistake is reading a file and then passing the resulting text to another function that expects a path. The value may look plausible in a print statement, so inspect its type as well as its content.

from pathlib import Path

path = Path("data/report.txt")
contents = path.read_text(encoding="utf-8")

print(type(path))
print(type(contents))
print(path)
print(contents[:20])

path is a path-like object and contents is a string containing file data. A string can be either a path or arbitrary text, so the receiving function cannot infer the caller’s intent. Keep variables named path, contents, or text to make that distinction visible.

Python Pool infographic comparing str, bytes, os.PathLike, pathlib.Path, and None — Path types: Str, bytes, os.PathLike, pathlib.Path, and None.

Pass pathlib.Path to file APIs

Modern Python file APIs accept Path objects directly. Build a path with the division operator and let pathlib handle separators. This avoids accidental path construction with a URL, a list of parts, or a platform-specific separator.

from pathlib import Path

base = Path("data")
input_path = base / "report.csv"
output_path = base / "report-clean.csv"

with input_path.open("r", encoding="utf-8") as handle:
    rows = handle.readlines()

output_path.write_text("".join(rows), encoding="utf-8")
print(output_path)

If a third-party library rejects Path, convert it at the boundary with os.fspath(path) or str(path) only after confirming that the library expects a filesystem string. Do not convert arbitrary objects just to silence the error; the resulting string may not be a valid path.

Use os.fspath() for path-like values

os.fspath() returns the filesystem representation of a string, bytes object, or object implementing __fspath__(). It is useful in helper functions that should accept both strings and Path objects. It also gives a consistent place to reject invalid inputs.

import os
from pathlib import Path

def describe_path(value):
    filesystem_value = os.fspath(value)
    return type(filesystem_value).__name__, filesystem_value

print(describe_path("data/report.csv"))
print(describe_path(Path("data/report.csv")))

A custom path-like class must return either str or bytes from __fspath__(). Returning file contents, a list, or another object violates the protocol and can produce a related TypeError at the point where the path is normalized.

Python Pool infographic showing open, join, exists, encoding, and path conversion — API boundary: Open, join, exists, encoding, and path conversion.

Do not pass file contents as a path

Functions often have separate parameters for a path and for data. If an API wants a filename, provide the path. If it wants a file-like object, pass an open handle. If it wants text, pass the contents only to the text parameter. Reading the documentation for the exact function is faster than guessing from a similar API.

from pathlib import Path

def read_first_line(path):
    path = Path(path)
    with path.open(encoding="utf-8") as handle:
        return handle.readline().rstrip("\n")

report_path = Path("data/report.txt")
print(read_first_line(report_path))

The helper accepts any value that Path() can interpret as a path. A list of path components is not automatically accepted as one path; use Path joining or os.path.join() to combine components before calling the helper.

Python Pool infographic showing pathlib.Path, os.fspath, validation, and explicit errors — Normalize path: Pathlib.Path, os.fspath, validation, and explicit errors.

Validate dynamic input before calling

Values from configuration files, forms, and JSON responses may be missing or have the wrong shape. Validate them at the boundary and report which field is wrong. This produces a useful application error instead of a low-level TypeError several functions later.

from pathlib import Path

def require_path(value, field="path"):
    if isinstance(value, (str, bytes, Path)):
        return Path(value)
    if hasattr(value, "__fspath__"):
        return Path(value)
    raise TypeError(f"{field} must be a filesystem path")

print(require_path("data/report.csv"))

The validation should match the contract of the downstream API. Some low-level operating-system calls accept bytes paths, while most application code is clearer with text paths and Path. Avoid accepting dictionaries or lists unless the helper explicitly converts a documented configuration shape.

Fix lists of path parts

A list such as ["data", "reports", "today.csv"] contains useful path parts but is not itself a path-like object. Join it with Path or os.path.join(). The resulting path can then be passed to an API that accepts filesystem paths.

from pathlib import Path

parts = ["data", "reports", "today.csv"]
path = Path(*parts)

print(path)
print(path.as_posix())

On Windows, Path uses the platform’s native path behavior. For a path that must be serialized or compared across systems, decide whether you need a native path, a POSIX-style representation, or a URI. These are different concepts and should not be mixed.

Python Pool infographic testing empty values, bytes, Windows, POSIX, and output — Path checks: Empty values, bytes, Windows, POSIX, and output.

Debug the exact call

When the traceback points into a library, inspect the last line in your own code and print the value immediately before the call. Use repr() so whitespace and escape characters are visible. If the value comes from a container, inspect the element that is being passed, not only the container itself.

def debug_path(value):
    print("type:", type(value).__name__)
    print("repr:", repr(value))
    if hasattr(value, "__fspath__"):
        print("filesystem value:", repr(value.__fspath__()))

debug_path(["data", "report.csv"])
debug_path("data/report.csv")

Do not log secrets or sensitive filenames in production. For a temporary local diagnosis, the type and a redacted representation are usually enough to identify whether the bug is a contents-versus-path mix-up.

Common mistakes

Passing file.read() to a function that expects a filename.
Passing a list of path parts without joining it first.
Using a URL where a local filesystem path is required.
Converting every object to str instead of validating the path contract.
Assuming a string is always a path when it may be file contents.

The stable fix is to establish the value’s role early: path, file handle, or contents. Use pathlib.Path for construction, os.fspath() at compatibility boundaries, and explicit validation for external input. Once those roles are separated, this TypeError becomes a useful signal rather than a mysterious library failure.

For practical path validation, compare getting a filename from a path with checking whether the path exists. Read python get filename from path and python check if file exists for the related workflow.