langchain-ai/deepagents · error · ToolRequirementIntrospectionError

uv tool receipt contains invalid extras on the tool requirem

Error message

uv tool receipt contains invalid extras on the tool requirement

What it means

The `extras` field on the deepagents-code requirement entry must be a list of valid extra names (per is_valid_extra_name). A non-list value, a non-string element, or a syntactically invalid extra name fails validation and raises ToolRequirementIntrospectionError.

Source

Thrown at libs/code/deepagents_code/update_check.py:3055

        unsupported_keys = sorted(
            str(key)
            for key in entry
            if not isinstance(key, str) or key not in {"name", "extras", "specifier"}
        )
        if unsupported_keys:
            fields = ", ".join(unsupported_keys)
            msg = (
                f"uv tool receipt requirement {name!r} uses source fields "
                f"that cannot be preserved automatically: {fields}"
            )
            raise ToolRequirementIntrospectionError(msg)
        extras = entry.get("extras", [])
        if not isinstance(extras, list) or any(
            not isinstance(extra, str) or not is_valid_extra_name(extra)
            for extra in extras
        ):
            msg = "uv tool receipt contains invalid extras on the tool requirement"
            raise ToolRequirementIntrospectionError(msg)
        normalized = {canonicalize_name(extra) for extra in extras}
        if len(normalized) != len(extras):
            msg = "uv tool receipt contains duplicate canonical extra names"
            raise ToolRequirementIntrospectionError(msg)
        return normalized

    msg = f"uv tool receipt does not contain a {distribution_name!r} requirement"
    raise ToolRequirementIntrospectionError(msg)


def _uv_tool_with_packages(
    *,
    distribution_name: str = "deepagents-code",
    tool_root: Path | None = None,
    data: dict[str, Any] | None = None,
) -> tuple[str, ...]:
    """Return package names recorded as uv tool `--with` requirements.

View on GitHub (pinned to a1af029e6e)

Solutions

Fix the receipt so extras is an array of valid identifier strings, e.g. `extras = ["all"]`.
Regenerate the receipt via `uv tool install deepagents-code --extra <name> --force`.
Check valid extra names against the deepagents-code package metadata before editing.

Example fix

// before
 [[tool.requirements]]
 name = "deepagents-code"
 extras = "all"
// after
 [[tool.requirements]]
 name = "deepagents-code"
 extras = ["all"]

Defensive patterns

Strategy: validation

Validate before calling

import tomllib

def extras_valid(data: dict, dist: str = 'deepagents-code') -> bool:
    for entry in (data.get('tool') or {}).get('requirements', []):
        if isinstance(entry, dict) and entry.get('name') == dist:
            extras = entry.get('extras', [])
            return isinstance(extras, list) and all(isinstance(e, str) and e.isidentifier() for e in extras)
    return True

Type guard

def is_valid_extras(value: object) -> bool:
    return isinstance(value, list) and all(isinstance(e, str) and bool(e) for e in value)

Try / catch

try:
    extras = _uv_tool_selected_extras()
except ToolRequirementIntrospectionError:
    subprocess.run(['uv', 'tool', 'install', 'deepagents-code', '--force'], check=True)
    extras = _uv_tool_selected_extras()

Prevention

Write extras as a TOML array of strings, never a single comma-joined string.
Verify extra names against the package's published extras before editing.
Use `uv tool install --extra <name>` to add extras so uv writes valid entries.
Skip extras surgery on receipts written by third-party tooling; reinstall instead.

When it happens

Trigger: _uv_tool_selected_extras reads entry.get("extras", []) and raises when it is not a list, contains non-strings, or contains strings failing is_valid_extra_name; reached via _uv_tool_install_command, dependency_refresh_dry_run_command, removable_extras, or uninstall_extra_command.

Common situations: Receipt hand-edited with a comma-joined string (`extras = "a,b"`) instead of an array; typo'd extra names with invalid characters; a receipt written by other tooling with a different extras representation.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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