langchain-ai/deepagents · error · RuntimeError

shell.allow_list is missing from the configuration manifest

Error message

shell.allow_list is missing from the configuration manifest

What it means

_resolve_shell_allow_list looks up the 'shell.allow_list' option in the configuration manifest before resolving its value. If the manifest has no such option — a broken or stale install, or an out-of-date/overridden manifest — it raises RuntimeError instead of silently returning an empty allow-list, since proceeding would misapply shell permissions.

Source

Thrown at libs/code/deepagents_code/agent.py:1102

    raise ValueError(msg)


def _resolve_shell_allow_list() -> list[str] | None:
    """Resolve the shell allow-list for a direct agent-construction caller.

    Returns:
        The configured allow-list, or `None` when shell access is disabled.

    Raises:
        RuntimeError: If the option is absent from the manifest.
    """
    from deepagents_code.config_manifest import _emit_ranked_diagnostics, get_option
    from deepagents_code.configuration.resolver import get_config_resolver

    option = get_option("shell.allow_list")
    if option is None:
        msg = "shell.allow_list is missing from the configuration manifest"
        raise RuntimeError(msg)
    resolved = get_config_resolver().get(option)
    _emit_ranked_diagnostics(option, resolved)
    return cast("list[str] | None", resolved.value)


def load_async_subagents(config_path: Path | None = None) -> list[AsyncSubAgent]:
    """Load async subagent definitions from `config.toml`.

    Reads the `[async_subagents]` section where each sub-table defines a remote
    LangGraph deployment:

    ```toml
    [async_subagents.researcher]
    description = "Research agent"
    url = "https://my-deployment.langsmith.dev"
    graph_id = "agent"
    ```

View on GitHub (pinned to a1af029e6e)

Solutions

1. Reinstall/upgrade the package cleanly (pip install --force-reinstall deepagents-code or refresh the editable install) so the manifest ships with shell.allow_list.
2. Check for path shadowing: python -c "import deepagents_code, deepagents_code.config_manifest as m; print(deepagents_code.__file__, m.get_option('shell.allow_list'))" and remove any stale duplicate on sys.path.
3. If you maintain a custom manifest, restore the shell.allow_list option entry.

Example fix

// before (custom manifest had the option removed)
// after — re-register the option in config_manifest
register_option("shell.allow_list", default=None, ...)

from deepagents_code.config_manifest import get_option

if get_option("shell.allow_list") is None:
    raise RuntimeError(
        "deepagents_code install is broken/stale: shell.allow_list missing; reinstall the package"
    )

null

try:
    agent = create_cli_agent()
except RuntimeError as exc:
    if "missing from the configuration manifest" in str(exc):
        raise SystemExit(
            "Broken deepagents_code install; run: pip install --force-reinstall deepagents-code"
        ) from exc
    raise

When it happens

Trigger: Calling create_cli_agent when get_option("shell.allow_list") returns None: partially installed or corrupted package where deepagents_code/config_manifest.py lacks the option entry; version mismatch where an old manifest is shadowing the current one; hand-patched manifest.

Common situations: Broken upgrade (mixed old/new package files), editable install pointing at an incomplete checkout, a local fork that removed the option from the manifest, stale .pyc or shadowing module named deepagents_code on sys.path.

Related errors

• Missing dependencies for '{provider}' sandbox. {install_hint
• StateBackend must be used inside a LangGraph graph execution
• StateBackend requires CONFIG_KEY_READ / CONFIG_KEY_SEND in t
• RubricMiddleware: `build_grader_state` cannot set `messages`
• RubricMiddleware grader did not return a structured_response

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