agentscope-ai/agentscope · error · OSError

container cp failed (exit {process.returncode}): {stderr.dec

Error message

container cp failed (exit {process.returncode}): {stderr.decode(errors='replace')}

What it means

AppleContainerWorkspace.write_file serializes bytes to a temp file and shells out to `container cp` to copy it into the container; a non-zero cp exit code raises OSError with the cp stderr. Indicates the container or destination path is broken.

Source

Thrown at src/agentscope/workspace/_applecontainer/_applecontainer_backend.py:207

            parent = posixpath.dirname(path)
            if parent and parent != "/":
                await self.exec_shell(
                    ["mkdir", "-p", parent],
                )

            # Copy the temp file into the container.
            container_path = f"{self._container_id}:{path}"
            process = await asyncio.create_subprocess_exec(
                "container",
                "cp",
                tmp_path,
                container_path,
                stdout=asyncio.subprocess.PIPE,
                stderr=asyncio.subprocess.PIPE,
            )
            _stdout, stderr = await process.communicate()
            if process.returncode != 0:
                raise OSError(
                    f"container cp failed (exit {process.returncode}): "
                    f"{stderr.decode(errors='replace')}",
                )
        finally:
            try:
                os.unlink(tmp_path)
            except OSError:
                pass

View on GitHub (pinned to e90f1c7592)

Solutions

Ensure the container is still running: await workspace.exec_shell(["true"]) as a health check, recreate if needed.
mkdir -p the parent directory inside the container before writing to a nested path.
Write to the workspace root or pre-create directory structure at provisioning.
Check stderr in the OSError message for the exact cp failure.

Example fix

# before
await ws.write_file("src/new_dir/main.py", data)

# after
await ws.exec_shell(["mkdir", "-p", "src/new_dir"])
await ws.write_file("src/new_dir/main.py", data)

Defensive patterns

Strategy: try-catch

Validate before calling

await ws.exec_shell(["mkdir", "-p", posixpath.dirname(path)])

Try / catch

try:
    await ws.write_file(path, data)
except OSError as e:
    if "container cp failed" in str(e):
        await ws.exec_shell(["mkdir", "-p", dirname])
        await ws.write_file(path, data)
    else:
        raise

Prevention

Pre-create destination directories inside the container.
Health-check the container before batch writes.
Parse the embedded cp stderr for root cause.

When it happens

Trigger: Calling await workspace.write_file(path, data) when the container is stopped/removed, the destination directory doesn't exist inside the container, permissions are wrong, or the Apple container CLI fails.

Common situations: Container was garbage-collected or stopped between operations, writing to a nested path whose parent directories don't exist in the container, disk pressure, or CLI version changes altering cp behavior.

Related errors

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/e6b43e6b9f0a504b. Report an issue: GitHub.