langchain-ai/deepagents · error · ValueError

Could not read rubric file {path!r}: {exc}.

Error message

Could not read rubric file {path!r}: {exc}.

What it means

`_resolve_rubric_text` raises `ValueError` when the file passed via `--rubric-file` cannot be read — either an OS-level error (missing file, permissions) or a decode error (binary or non-UTF-8 content). The code deliberately catches `UnicodeError` alongside `OSError` so users get one framed message instead of a raw codec traceback.

Source

Thrown at libs/code/deepagents_code/main.py:1533

    """
    if rubric is None:
        return None

    # An `@`-prefixed value is always read as a file path. The path may be
    # absolute, relative to the `dcode` process working directory, or `~`-based.
    # There is no way to pass a literal rubric that begins with `@` (put such
    # text in a file).
    if rubric.startswith("@"):
        path = rubric[1:]
        try:
            text = Path(path).expanduser().read_text(encoding="utf-8")
        except (OSError, UnicodeError) as exc:
            # `UnicodeError` (e.g. `UnicodeDecodeError`) subclasses `ValueError`,
            # not `OSError`. Catch it here so a binary/non-UTF-8 file yields the
            # framed "Could not read rubric file" message instead of a raw codec
            # error.
            msg = f"Could not read rubric file {path!r}: {exc}."
            raise ValueError(msg) from exc
        if not text.strip():
            msg = f"Rubric file {path!r} is empty."
            raise ValueError(msg)
        resolved = text.strip()
        validate_rubric(resolved)
        return resolved

    if not rubric.strip():
        msg = "--rubric must not be empty."
        raise ValueError(msg)
    resolved = rubric.strip()
    validate_rubric(resolved)
    return resolved


# The standalone `validate_rubric` above is sufficient here, unlike `/rubric next`,
# which additionally runs the combined notice check via `_next_rubric_size_error`.
# That check exists because an in-session one-shot rubric is embedded in the notice

View on GitHub (pinned to a1af029e6e)

Solutions

1. Verify the path exists and is readable (`ls -l <path>`), correcting typos
2. Re-save the rubric file as UTF-8 (e.g. `iconv -f UTF-16 -t UTF-8 rubric.txt > rubric-utf8.txt`)
3. If the file is genuinely binary, recreate it as plain text

Example fix

// before
iconv -f UTF-16 -t UTF-8 rubric.txt  # silently mis-decoded or binary content
// after
file -i rubric.txt  # confirm charset
iconv -f UTF-16 -t UTF-8 rubric.txt > rubric-utf8.txt
deepagents-code --rubric-file rubric-utf8.txt

from pathlib import Path

def readable_utf8_file(path: str) -> bool:
    p = Path(path)
    if not p.is_file():
        return False
    try:
        p.read_text(encoding="utf-8")
        return True
    except (OSError, UnicodeError):
        return False

# before: --rubric-file <path>
assert readable_utf8_file(path), f"{path} missing or not UTF-8"

try:
    rubric = _resolve_rubric_text(args)
except ValueError as exc:
    raise SystemExit(f"bad rubric input: {exc}")

When it happens

Trigger: `cli_main --rubric-file <path>` where the path does not exist, is a directory, lacks read permission, or contains non-UTF-8 bytes (e.g. a UTF-16 or Latin-1 encoded rubric, or a binary file).

Common situations: Typo in the rubric file path; file created on Windows with UTF-16 BOM encoding; rubric exported as a Word/PDF binary; file moved or deleted between shell completion and invocation.

Related errors

• Could not resolve {label} path {raw_path!r}: {exc}. Ensure t
• Error: Could not create project skills directory.
• Error: Cannot determine base skills directory. Refusing to d
• Error: Failed to fully delete skill: {e} Warning: Some files
• Error: Could not clear trusted directories.

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