langchain-ai/deepagents · error · ExtensionError

Extension factory in {source.path} failed: {exc}

Error message

Extension factory in {source.path} failed: {exc}

What it means

Raised by `load_extension` when an extension factory raises any exception other than `SystemExit` while executing. The loader cleans the module out of `sys.modules` and wraps the failure in `ExtensionError`, preserving the original exception via `raise ... from exc` so the root cause stays in the traceback.

Source

Thrown at libs/code/deepagents_code/extensions/loader.py:109

    snapshot = registry._snapshot()
    api = ExtensionAPI(registry, source, cwd=cwd, mode=mode)
    try:
        await factory(api)
    except (KeyboardInterrupt, asyncio.CancelledError):
        registry._rollback(snapshot)
        api._deactivate()
        sys.modules.pop(name, None)
        raise
    except (SystemExit, Exception) as exc:
        registry._rollback(snapshot)
        api._deactivate()
        sys.modules.pop(name, None)
        msg = (
            f"Extension factory in {source.path} attempted to exit: {exc}"
            if isinstance(exc, SystemExit)
            else f"Extension factory in {source.path} failed: {exc}"
        )
        raise ExtensionError(msg) from exc
    return api

View on GitHub (pinned to a1af029e6e)

Solutions

1. Read the chained `__cause__` traceback to find the real failing line in the factory
2. Install or fix whatever dependency/resource the factory failed on
3. Wrap risky setup in the factory and raise a descriptive error, or defer non-essential work to first use

Example fix

// before
async def extension(api):
    client = ExpensiveClient(api.config["token"])  # KeyError if missing

// after
async def extension(api):
    token = api.config.get("token")
    if not token:
        raise RuntimeError("'token' is required in the [tools.search] config")
    client = ExpensiveClient(token)

# pre-flight: import the extension module and dry-run its factory deps
try:
    importlib.import_module(ext_module_name)
except ImportError as exc:
    logger.error("extension dep missing: %s", exc)

try:
    api = await load_extension(source, registry)
except ExtensionError as exc:
    logger.exception("extension %s failed", source.path)  # chained cause shown

When it happens

Trigger: Any uncaught exception inside the async factory body: failed imports at factory time, network/filesystem errors during init, attribute errors on the injected API, bad config reads, constructor exceptions.

Common situations: Extensions importing optional dependencies that are not installed; factories reading config files that are malformed or absent; API version drift where the factory calls an API method that no longer exists.

Related errors

• {source.path} does not define a callable 'extension' factory
• Extension factory in {source.path} must be declared with 'as
• Extension factory in {source.path} attempted to exit: {exc}
• Extension registration is closed for this session
• Could not construct middleware {middleware!r}: {exc}

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