langchain-ai/deepagents · error · RuntimeError

langgraph.json not found in {work_dir}. Call generate_langgr

Error message

langgraph.json not found in {work_dir}. Call generate_langgraph_json() first.

What it means

`_spawn_process` requires `langgraph.json` in the server workspace before launching; if rescaffolding is unavailable (no `_scaffold` callable) and the config file is absent, it raises `RuntimeError` instructing the caller to generate the config first.

Source

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

                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
                )
            elif _port_in_use(self.host, self.port):
                self.port = _find_free_port(self.host)
                logger.info("Requested port in use, using port %d instead", self.port)

            cmd = _build_server_cmd(config_path, host=self.host, port=self.port)
            env = _server_env_with_overrides(
                self._persistent_env_overrides, self._env_overrides
            )

            logger.info("Starting langgraph dev server: %s", " ".join(cmd))
            self._log_file = tempfile.NamedTemporaryFile(  # noqa: SIM115
                prefix="deepagents_server_log_",

View on GitHub (pinned to a1af029e6e)

Solutions

1. Call `generate_langgraph_json()` on the server/manager before `start()` to create the config
2. Verify the work_dir you pass is the one where the config was generated
3. Regenerate the config if it was deleted, or point at a workspace that retains `langgraph.json`
4. Provide a `_scaffold` hook so the launcher can self-heal a missing config

Example fix

// before
server = LanggraphServer(work_dir=empty_dir)
await server.start()  # no langgraph.json
// after
generate_langgraph_json(work_dir=empty_dir)
server = LanggraphServer(work_dir=empty_dir)
await server.start()

cfg = work_dir / "langgraph.json"
if not cfg.exists():
    generate_langgraph_json(work_dir)
assert cfg.exists(), "langgraph.json still missing after generation"

def has_langgraph_config(work_dir) -> bool:
    return (work_dir / "langgraph.json").is_file()

try:
    await server._start()
except RuntimeError as e:
    if "langgraph.json not found" in str(e):
        generate_langgraph_json(server.work_dir)
        await server._start()
    else:
        raise

When it happens

Trigger: Starting the server against a bare/empty work_dir where `generate_langgraph_json()` was never called and no scaffold hook is configured, or the config was deleted between generation and launch.

Common situations: Manually constructing `LanggraphServer` with a fresh directory and calling `start()` without the generate step; cleaning temp dirs while a server session expects them; misconfigured work_dir pointing to an uninitialized path.

Related errors

• modes can only be provided when agent is a factory
• models can only be provided when agent is a factory
• -32601
• -32002
• -32602

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