langchain-ai/deepagents · error · FleetImportError

{target}: {exc}

Error message

{target}: {exc}

What it means

FleetImportError raised by `import_fleet_zip` when an OSError occurs during archive validation, staging, or refreshing the target directory. The message is `f"{target}: {exc}"`, so it names the destination and embeds the OS-level reason (permission denied, disk full, read-only filesystem, etc.).

Source

Thrown at libs/talon/deepagents_talon/fleet_import.py:161

        with zipfile.ZipFile(source) as archive:
            entries = _validated_entries(archive)
            if "AGENTS.md" not in entries:
                msg = "AGENTS.md: missing required root prompt"
                raise FleetImportError(msg)
            with tempfile.TemporaryDirectory(prefix="deepagents-talon-import-") as raw:
                staging = Path(raw)
                _materialize_staging(archive, entries, staging)
                summaries = _mcp_summaries(staging, source)
                notes = _format_setup_notes(source.name, summaries)
                mcp_config = _format_mcp_config(summaries)
                config_ignored = (staging / "config.json").is_file()
                _refresh_target(staging, target, home, notes, mcp_config)
    except zipfile.BadZipFile as exc:
        msg = f"{source}: invalid zip file"
        raise FleetImportError(msg) from exc
    except OSError as exc:
        msg = f"{target}: {exc}"
        raise FleetImportError(msg) from exc

    return FleetImportResult(
        target_dir=target,
        root_prompt_count=1,
        subagent_prompt_count=len(_subagent_prompt_paths(home)),
        config_ignored=config_ignored,
        mcp_notes=notes,
        interrupt_tools=tuple(
            sorted({tool for summary in summaries for tool in summary.interrupt_tools})
        ),
    )


def format_import_stdout(result: FleetImportResult) -> str:
    """Render a concise user-facing import summary.

    Args:
        result: Completed import summary.

View on GitHub (pinned to a1af029e6e)

Solutions

1. Check and fix permissions on the target directory (`ls -ld`, `chmod`/`chown` or run with appropriate rights).
2. Verify the target's parent directory exists and the filesystem has free space (`df -h`).
3. Ensure the target is not on a read-only mount before importing.

Example fix

// before
import_fleet_zip(zip_path, Path("/system/readonly/assistant"))
// after
Path("/system/readonly/assistant").parent.mkdir(parents=True, exist_ok=True)
import_fleet_zip(zip_path, Path("/home/user/.deepagents"))

target = Path(target_dir)
if not target.parent.exists() or not os.access(target.parent, os.W_OK):
    raise RuntimeError(f"cannot write to {target.parent}")
import shutil
if shutil.disk_usage(target.parent).free < 50_000_000:
    raise RuntimeError("insufficient disk space")

from deepagents_talon.fleet_import import import_fleet_zip, FleetImportError
try:
    result = import_fleet_zip(source, target)
except FleetImportError as exc:
    if isinstance(exc.__cause__, OSError):
        raise SystemExit(f"fix filesystem issue for {target}: {exc.__cause__}") from exc
    raise

When it happens

Trigger: Calling `import_fleet_zip` where the target/home path is not writable, the parent directory is missing, the filesystem is full, or an existing target file is read-only — any OSError raised inside the try block at libs/talon/deepagents_talon/fleet_import.py:159.

Common situations: Running without write permission on the install target; importing into a container path mounted read-only; disk quota exceeded mid-extraction; target owned by another user.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• Could not read marketplace manifest {manifest_path}: {exc}
• could not update {DEFAULT_CONFIG_PATH}
• debug log directory is not owned by the current user: {path}
• Cannot determine whether {str(left)!r} is {str(right)!r}: {e
• Invalid DEEPAGENTS_HOME {str(root)!r}: exists but cannot be

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