{"record":{"id":"7d6db4e8f9591ee7","repo":"langchain-ai/deepagents","slug":"shell-allow-list-is-missing-from-the-configuration","errorCode":null,"errorMessage":"shell.allow_list is missing from the configuration manifest","messagePattern":"shell\\.allow_list is missing from the configuration manifest","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/agent.py","lineNumber":1102,"sourceCode":"    raise ValueError(msg)\n\n\ndef _resolve_shell_allow_list() -> list[str] | None:\n    \"\"\"Resolve the shell allow-list for a direct agent-construction caller.\n\n    Returns:\n        The configured allow-list, or `None` when shell access is disabled.\n\n    Raises:\n        RuntimeError: If the option is absent from the manifest.\n    \"\"\"\n    from deepagents_code.config_manifest import _emit_ranked_diagnostics, get_option\n    from deepagents_code.configuration.resolver import get_config_resolver\n\n    option = get_option(\"shell.allow_list\")\n    if option is None:\n        msg = \"shell.allow_list is missing from the configuration manifest\"\n        raise RuntimeError(msg)\n    resolved = get_config_resolver().get(option)\n    _emit_ranked_diagnostics(option, resolved)\n    return cast(\"list[str] | None\", resolved.value)\n\n\ndef load_async_subagents(config_path: Path | None = None) -> list[AsyncSubAgent]:\n    \"\"\"Load async subagent definitions from `config.toml`.\n\n    Reads the `[async_subagents]` section where each sub-table defines a remote\n    LangGraph deployment:\n\n    ```toml\n    [async_subagents.researcher]\n    description = \"Research agent\"\n    url = \"https://my-deployment.langsmith.dev\"\n    graph_id = \"agent\"\n    ```\n","sourceCodeStart":1084,"sourceCodeEnd":1120,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/agent.py#L1084-L1120","documentation":"_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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reinstall/upgrade the package cleanly (pip install --force-reinstall deepagents-code or refresh the editable install) so the manifest ships with shell.allow_list.","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.","If you maintain a custom manifest, restore the shell.allow_list option entry."],"exampleFix":"// before (custom manifest had the option removed)\n// after — re-register the option in config_manifest\nregister_option(\"shell.allow_list\", default=None, ...)","handlingStrategy":"try-catch","validationCode":"from deepagents_code.config_manifest import get_option\n\nif get_option(\"shell.allow_list\") is None:\n    raise RuntimeError(\n        \"deepagents_code install is broken/stale: shell.allow_list missing; reinstall the package\"\n    )","typeGuard":"null","tryCatchPattern":"try:\n    agent = create_cli_agent()\nexcept RuntimeError as exc:\n    if \"missing from the configuration manifest\" in str(exc):\n        raise SystemExit(\n            \"Broken deepagents_code install; run: pip install --force-reinstall deepagents-code\"\n        ) from exc\n    raise","preventionTips":["Reinstall cleanly after upgrades; avoid mixed old/new package files.","Check for a shadowing deepagents_code directory on sys.path in your environment.","Verify integrity in CI: python -c \"from deepagents_code.config_manifest import get_option; assert get_option('shell.allow_list') is not None\"."],"tags":["python","runtime-error","configuration-manifest","installation"],"backgroundTag":"missing-config-option","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}