langchain-ai/deepagents · error · ValueError

`{field_name}` entries must be non-empty, non-whitespace str

Error message

`{field_name}` entries must be non-empty, non-whitespace strings

What it means

HarnessProfileConfig middleware-list validation rejects entries that are empty or whitespace-only strings. The library requires every configured middleware name to be a usable identifier so exclusion lookups against the middleware registry are unambiguous. This is raised eagerly in `__post_init__` so bad configs fail at construction time rather than at agent creation.

Source

Thrown at libs/deepagents/deepagents/profiles/harness/harness_profiles.py:899

    Scaffolding-class/name rejection and matched-something coverage are
    deliberately NOT checked here — those need the fully assembled middleware
    stack.

    Args:
        entry: Candidate entry. Must be a string to pass.
        field_name: Field being validated, used for error messages.

    Raises:
        TypeError: If `entry` is not a string.
        ValueError: If `entry` violates any of the grammar rules above.
    """
    if not isinstance(entry, str):
        msg = f"`{field_name}` entries must be strings, got {type(entry).__name__} ({entry!r})"
        raise TypeError(msg)
    if not entry or entry.isspace():
        msg = f"`{field_name}` entries must be non-empty, non-whitespace strings"
        raise ValueError(msg)
    if ":" in entry:
        msg = (
            f"`{field_name}` entries must be plain middleware names; class-path (`module:Class`) entries are not currently supported, got {entry!r}."
        )
        raise ValueError(msg)
    if entry.startswith("_"):
        msg = (
            f"`{field_name}` entry {entry!r} cannot start with '_' "
            f"(underscore-prefixed names refer to private middleware classes "
            f"not part of the public exclusion surface)."
        )
        raise ValueError(msg)


def _serialize_runtime_excluded_middleware_entry(
    entry: type[AgentMiddleware] | str,
) -> str:
    """Serialize a runtime `excluded_middleware` entry back to config form.

View on GitHub (pinned to a1af029e6e)

Solutions

1. Remove the empty/whitespace entry from the middleware list in your config
2. If the value comes from an env var or split string, filter out blanks before constructing the config: `[e for e in raw.split(',') if e.strip()]`
3. Fix the source config file (YAML/JSON) to omit the item entirely instead of supplying an empty string

Example fix

# before
config = HarnessProfileConfig(excluded_middleware=["websearch", ""])
# after
config = HarnessProfileConfig(excluded_middleware=["websearch"])

names = cfg.get("excluded_middleware", [])
bad = [n for n in names if not isinstance(n, str) or not n.strip()]
if bad:
    raise ValueError(f"blank middleware entries: {bad!r}")

def is_valid_middleware_name(entry: object) -> TypeGuard[str]:
    return isinstance(entry, str) and bool(entry) and not entry.isspace()

try:
    config = HarnessProfileConfig(**raw)
except ValueError as e:
    if "non-empty, non-whitespace" in str(e):
        raw["excluded_middleware"] = [n for n in raw.get("excluded_middleware", []) if isinstance(n, str) and n.strip()]
        config = HarnessProfileConfig(**raw)
    else:
        raise

When it happens

Trigger: Constructing or deserializing a HarnessProfileConfig (e.g. via `HarnessProfileConfig(**data)` or loading YAML/JSON config) with an `excluded_middleware` (or similar middleware string list) containing `""`, `" "`, or `"\t"`.

Common situations: Hand-edited config files with trailing comma leaving a blank item; template placeholders never filled in; programmatic list building that appends empty strings from splitting `"a,,b"`; env-var-driven config where the var is set to whitespace.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• `{field_name}` entries must be plain middleware names; class
• `{field_name}` entry {entry!r} cannot start with '_' (unders
• modes can only be provided when agent is a factory
• models can only be provided when agent is a factory
• -32602

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