langchain-ai/deepagents · error · RuntimeError

Failed to rescaffold server workspace at {work_dir}: {exc}

Error message

Failed to rescaffold server workspace at {work_dir}: {exc}

What it means

`_spawn_process` re-scaffolds the server workspace when `langgraph.json` is missing, but if the `mkdir`/`_scaffold` call raises `OSError` (permissions, read-only filesystem, disk full), it re-raises as `RuntimeError` with the workspace path and the original OS error.

Source

Thrown at libs/code/deepagents_code/client/launch/server.py:937

                return None
            self._stopped = False

            work_dir = self.config_dir
            if work_dir is None:
                self._temp_dir = tempfile.TemporaryDirectory(
                    prefix="deepagents_server_"
                )
                work_dir = Path(self._temp_dir.name)

            config_path = work_dir / "langgraph.json"
            if not config_path.exists() and self._scaffold is not None:
                logger.info("langgraph.json missing in %s; rescaffolding", work_dir)
                try:
                    work_dir.mkdir(parents=True, exist_ok=True)
                    self._scaffold(work_dir)
                except OSError as exc:
                    msg = f"Failed to rescaffold server workspace at {work_dir}: {exc}"
                    raise RuntimeError(msg) from exc
            if not config_path.exists():
                if self._scaffold is not None:
                    contents = sorted(p.name for p in work_dir.iterdir())
                    msg = (
                        f"Rescaffolding {work_dir} did not produce langgraph.json "
                        f"(directory contents: {contents})."
                    )
                else:
                    msg = (
                        f"langgraph.json not found in {work_dir}. "
                        "Call generate_langgraph_json() first."
                    )
                raise RuntimeError(msg)

            if self.port == _EPHEMERAL_PORT:
                self.port = _find_free_port(self.host)
                logger.info(
                    "Using ephemeral port %d for langgraph dev server", self.port

View on GitHub (pinned to a1af029e6e)

Solutions

1. Ensure the process has write permission on the work_dir (chmod/chown or run as the right user)
2. Point the launcher at a writable workspace directory
3. Check the underlying `exc` text in the message for the precise OS cause (EACCES, EROFS, ENOSPC)
4. Pre-generate `langgraph.json` (call `generate_langgraph_json()`) so rescaffolding is never attempted

Example fix

// before
work_dir = Path("/opt/readonly/workspace")  # not writable
// after
work_dir = Path.home() / ".deepagents_code" / "workspace"  # writable

import os
work_dir.mkdir(parents=True, exist_ok=True)
if not os.access(work_dir, os.W_OK):
    raise PermissionError(f"{work_dir} is not writable")

def workspace_writable(path) -> bool:
    import os
    return path.is_dir() and os.access(path, os.W_OK)

try:
    await server._start()
except RuntimeError as e:
    if str(e).startswith("Failed to rescaffold"):
        logger.error("rescaffold failed: %s", e)
        # switch to a writable dir and regenerate config
        server.work_dir = writable_dir
        generate_langgraph_json(server.work_dir)
        await server._start()
    else:
        raise

When it happens

Trigger: Launcher starts against a work_dir lacking `langgraph.json` and scaffolding fails: directory not writable, workspace on a read-only mount, parent path not creatable, or disk quota exhausted.

Common situations: Running under a restricted user/CI container without write access to the cache/work directory, sandboxed environments blocking writes, or an immutable deployment filesystem.

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

• 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
• Failed to read credential file {path}: {exc}. Check the file
• Failed to write credential file {auth_path()}: {exc}. Check

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