langchain-ai/deepagents · error · SystemExit

Error: Invalid agent name: {error_msg}

Error message

Error: Invalid agent name: {error_msg}

What it means

`execute_skills_command` validates the `--agent` argument's name before using it, printing `Error: Invalid agent name: <error_msg>` plus a hint that agent names may only contain letters, numbers, hyphens, and underscores, then exits with status 1. The check prevents invalid characters from reaching paths or configuration keyed by agent name.

Source

Thrown at libs/code/deepagents_code/skills/commands.py:1228

    # The `trust` subcommand manages directory paths, not agent-scoped skills,
    # so it has no `--agent` and is dispatched before agent validation.
    if args.skills_command == "trust":
        _trust(args)
        return

    # validate agent argument
    if getattr(args, "agent", None):
        is_valid, error_msg = _validate_name(args.agent)
        if not is_valid:
            console.print(
                f"[bold red]Error:[/bold red] Invalid agent name: {error_msg}"
            )
            console.print(
                "[dim]Agent names must only contain letters, numbers, "
                "hyphens, and underscores.[/dim]",
                style=theme.MUTED,
            )
            raise SystemExit(1)

    output_format = getattr(args, "output_format", "text")

    # "ls" is an argparse alias for "list" — argparse stores the alias
    # as-is in the namespace, so we must match both values.
    if args.skills_command in {"list", "ls"}:
        _list(agent=args.agent, project=args.project, output_format=output_format)
    elif args.skills_command == "create":
        _create(
            args.name,
            agent=args.agent,
            project=args.project,
            output_format=output_format,
        )
    elif args.skills_command == "info":
        _info(
            args.name,
            agent=args.agent,

View on GitHub (pinned to a1af029e6e)

Solutions

1. Use only letters, numbers, hyphens, and underscores in the --agent value
2. Quote the argument in the shell and avoid path-like values (no `/`, `.`, spaces)
3. List available agents and use the exact internal identifier

Example fix

// before
$ dcode skills list --agent "My Agent.01"
# Error: Invalid agent name: ...
// after
$ dcode skills list --agent my-agent-01

import re

def is_valid_agent_name(name: str) -> bool:
    return bool(re.fullmatch(r'[A-Za-z0-9_-]+', name))

When it happens

Trigger: Invoking a skills subcommand with `--agent` whose value contains characters outside `[A-Za-z0-9_-]` (spaces, dots, slashes, unicode) so the validation routine produces an `error_msg`.

Common situations: Passing an agent display name with spaces instead of its identifier; shell interpolation inserting slashes or dots; copy-pasting an agent label from docs or UI that differs from its internal name.

Related errors

• --model-params requires a JSON object value
• Unclosed {quote} in --model-params value
• Unbalanced braces in --model-params value
• Cannot combine 'all' with other commands in --shell-allow-li
• cli_max_retries must be >= 0, got {self.cli_max_retries}

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