langchain-ai/deepagents · error · MarketplaceError

Installed {plugin_id} but failed to load from cache: {detail

Error message

Installed {plugin_id} but failed to load from cache: {detail}

What it means

`install_plugin` copies a marketplace plugin into the versioned cache, enables it, and then re-loads it from the cache path via `_plugin_from_install_path`. If the cached copy fails to produce a `PluginInstance` (manifest missing/invalid, inventory build problems, or `PluginInstance` raising `ValueError`), the install record is rolled back with `uninstall_plugin_record` and this `MarketplaceError` is raised with the collected load warnings as the detail.

Source

Thrown at libs/code/deepagents_code/plugins/discovery.py:264

            plugin_id=plugin_id,
            fallback_name=entry.name,
        ),
    )

    set_plugin_enabled(plugin_id, True)
    ensure_plugin_data_dir(plugin_id)

    instance, warnings = _plugin_from_install_path(
        plugin_id=plugin_id,
        root=cache_path,
        marketplace_name=marketplace.name,
        fallback_name=entry.name,
    )
    if instance is None:
        detail = "; ".join(warnings)
        uninstall_plugin_record(plugin_id)
        msg = f"Installed {plugin_id} but failed to load from cache: {detail}"
        raise MarketplaceError(msg)
    return instance


def _validate_plugin_copy(
    root: Path,
    *,
    plugin_id: str,
    fallback_name: str,
) -> None:
    try:
        manifest, _manifest_path, warnings = load_manifest(
            root, fallback_name=fallback_name
        )
    except PluginManifestError as exc:
        msg = f"Cannot install {plugin_id}: {exc}"
        raise MarketplaceError(msg) from exc
    build_inventory(root, manifest, warnings)

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Read the `detail` suffix of the message; it lists the exact load warnings.
  2. Check the plugin's source repo manifest and component paths (`./agents`, `./commands`, etc.) are valid and real files (not dangling or out-of-root symlinks).
  3. Clear the plugin cache directory for that plugin and reinstall.
  4. Update the plugin in its marketplace source, then reinstall.
  5. If you hit this from a test, verify the test fixture copies real files rather than symlinks outside the plugin root.

Example fix

// before: plugin has a dangling symlink component
commands -> /outside/commands  (not copied into cache)
// after
commands/
  review.md  (real file inside the plugin root)
Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
for rel in ("plugin.json", ".deepagents/plugin.json"):
    if (root / rel).is_file():
        import json; json.loads((root / rel).read_text())  # raises if malformed

Type guard

def is_loadable_plugin(root: Path) -> bool:
    try:
        manifest, _, _ = load_manifest(root)
        return manifest is not None
    except PluginManifestError:
        return False

Try / catch

try:
    install_plugin(plugin_id)
except MarketplaceError as exc:
    logger.warning("install failed: %s", exc)  # detail lists load warnings
    # optionally: clear cache dir for plugin_id and retry once

Prevention

When it happens

Trigger: Calling `install_plugin(plugin_id)` when the plugin's cached copy fails to load: the manifest cannot be parsed from the cache path, component inventory build warns/fails, or `PluginInstance` construction raises `ValueError` (the warning strings joined into `detail` tell which).

Common situations: Upstream plugin repo ships a valid manifest at the source but the copy step drops files (e.g. symlinked components outside the plugin root); cache corruption; a manifest that validates loosely but produces warnings making the cached instance unusable; platform-specific path issues after install.

Related errors

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