langchain-ai/deepagents · error · ValueError

media path is not a regular file: {path}

Error message

media path is not a regular file: {path}

What it means

resolve_bounded_media_path resolves a user-supplied media path against an outbound root and then validates it. This ValueError is raised when the resolved path exists inside the allowed root but is not a regular file (e.g. a directory, FIFO, or device node), because only regular files can be safely attached as outbound channel media.

Source

Thrown at libs/talon/deepagents_talon/media.py:237

        msg = f"media path must be a local relative path under the outbound root: {path}"
        raise ValueError(msg)
    if ".." in path.parts or ".." in windows_path.parts:
        msg = f"media path must not contain parent-directory traversal: {path}"
        raise ValueError(msg)

    root_resolved = root.expanduser().resolve()
    candidate_input = root_resolved / path if not path.is_absolute() else path
    try:
        candidate = candidate_input.resolve(strict=True)
    except OSError as exc:
        msg = f"media file is unavailable: {path}"
        raise ValueError(msg) from exc
    if not candidate.is_relative_to(root_resolved):
        msg = f"media path escapes outbound root: {path}"
        raise ValueError(msg)
    if not candidate.is_file():
        msg = f"media path is not a regular file: {path}"
        raise ValueError(msg)
    return candidate


def _document_parts(paths: list[Path]) -> list[str]:
    parts: list[str] = []
    for path in paths:
        if path.suffix.lower() not in READABLE_DOCUMENT_EXTENSIONS:
            parts.append(f"_(Received unsupported document attachment: {path.name}.)_")
            continue
        try:
            if path.stat().st_size > MAX_TEXT_DOCUMENT_BYTES:
                parts.append(f"_(Document attachment is too large to read inline: {path.name}.)_")
                continue
            content = path.read_text(encoding="utf-8", errors="replace")
        except OSError:
            parts.append(f"_(Document attachment was unavailable: {path.name}.)_")
            continue
        parts.append(f"[Content of {path.name}]:\n{content}")

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass the path to an actual regular file, not a directory or special file
2. Check the path with `Path(p).is_file()` before calling and fix the upstream producer of the file
3. If a symlink is involved, resolve it (`Path.resolve()`) and confirm the target is a regular file inside the outbound root

Example fix

// before
outbound_channel_media(channel, "/outbound/media/attachments")
// after
path = Path("/outbound/media/attachments/report.pdf")
if not path.is_file():
    raise FileNotFoundError(f"expected a regular file at {path}")
outbound_channel_media(channel, path)

from pathlib import Path

def ensure_attachable(path: str | Path, root: Path) -> Path:
    candidate = Path(path).resolve()
    root_resolved = root.resolve()
    if not candidate.is_relative_to(root_resolved):
        raise ValueError(f"{path} escapes outbound root {root}")
    if not candidate.is_file():
        raise ValueError(f"{path} is not a regular file")
    return candidate

ensure_attachable("/outbound/media/report.pdf", Path("/outbound/media"))

def is_regular_file_under(p: Path, root: Path) -> bool:
    try:
        return p.resolve().is_file() and p.resolve().is_relative_to(root.resolve())
    except OSError:
        return False

When it happens

Trigger: Calling resolve_bounded_media_path (directly or via validate_media / outbound_channel_media) with a path that points to a directory, symlink-to-directory, socket, or other non-regular filesystem entry inside the outbound root.

Common situations: Passing a directory instead of a file path to an outbound media attachment; a build/export step left an empty directory where the file was expected; a media pipeline produced a special file (pipe/socket) instead of a regular file.

Related errors

• suffix must be empty or a short extension such as .md
• temporary artifact is not a regular file
• Path does not exist: {path}
• File path must point to a .json marketplace file: {path}
• workspace.{field} is not a directory: {value}

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/087f32d1c3a53409. Report an issue: GitHub.