langchain-ai/deepagents · error · FleetImportError

{source}: {_display_path(path)}: tools[{index}].{key} must b

Error message

{source}: {_display_path(path)}: tools[{index}].{key} must be a non-empty string

What it means

FleetImportError raised by _required_str when a required string field on a tools.json entry is missing, not a string, or an empty string. Used for fields like name, mcp_server_url, and mcp_server_name.

Source

Thrown at libs/talon/deepagents_talon/fleet_import.py:403

                server_name=server_name,
                scope=scope,
                interrupt=_tool_interrupt_enabled(tool, interrupts, name, server_url, server_name),
            )
        )
    return requests


def _required_str(
    item: Mapping[str, object],
    key: str,
    path: Path,
    index: int,
    source: Path,
) -> str:
    value = item.get(key)
    if not isinstance(value, str) or not value:
        msg = f"{source}: {_display_path(path)}: tools[{index}].{key} must be a non-empty string"
        raise FleetImportError(msg)
    return value


def _tool_interrupt_enabled(
    item: Mapping[str, object],
    interrupts: Mapping[object, object],
    name: str,
    server_url: str,
    server_name: str,
) -> bool:
    if item.get("interrupt_config") is True:
        return True
    keys = (
        f"{server_url}::{name}::{server_name}",
        f"{_unsanitized_url(item)}::{name}::{server_name}",
        name,
    )
    return any(interrupts.get(key) is True for key in keys)

View on GitHub (pinned to a1af029e6e)

Solutions

Set the named key at tools[index] to a non-empty string (e.g. a valid MCP server URL)
Check for key renames/spelling differences between your file and the expected schema
Re-generate the tools.json from the fleet source to get correct defaults

Example fix

// before
{"name": "", "mcp_server_url": "https://example.com", "mcp_server_name": "example"}
// after
{"name": "my-tool", "mcp_server_url": "https://example.com", "mcp_server_name": "example"}

Defensive patterns

Strategy: validation

Validate before calling

REQUIRED = ("name", "mcp_server_url", "mcp_server_name")
for i, tool in enumerate(data["tools"]):
    missing = [k for k in REQUIRED if not isinstance(tool.get(k), str) or not tool.get(k)]
    if missing:
        raise ValueError(f"tools[{i}] missing/empty: {missing}")

Type guard

def is_nonempty_str(v: object) -> TypeGuard[str]:
    return isinstance(v, str) and bool(v)

Try / catch

try:
    summaries = _mcp_summaries(...)
except FleetImportError as exc:
    logger.error("tools.json field invalid: %s", exc)
    raise

Prevention

Fill all template placeholders; grep for empty string values before import
Keep a schema/example tools.json checked into the repo
Check key names against the expected schema after any rename

When it happens

Trigger: A tool object in tools.json omits a required key, sets it to null/number/bool, or sets it to ""; the error names the exact index and key.

Common situations: Placeholder values left as empty strings after template fill; renaming a key (e.g. 'server' vs 'mcp_server_name'); YAML-to-JSON conversion turning empty values into null or omitting them.

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/ed6b3ab2c85b1e84. Report an issue: GitHub.