{"record":{"id":"78b8693471a2ef98","repo":"langchain-ai/deepagents","slug":"failed-to-rescaffold-server-workspace-at-work-dir","errorCode":null,"errorMessage":"Failed to rescaffold server workspace at {work_dir}: {exc}","messagePattern":"Failed to rescaffold server workspace at (.+?): (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/client/launch/server.py","lineNumber":937,"sourceCode":"                return None\n            self._stopped = False\n\n            work_dir = self.config_dir\n            if work_dir is None:\n                self._temp_dir = tempfile.TemporaryDirectory(\n                    prefix=\"deepagents_server_\"\n                )\n                work_dir = Path(self._temp_dir.name)\n\n            config_path = work_dir / \"langgraph.json\"\n            if not config_path.exists() and self._scaffold is not None:\n                logger.info(\"langgraph.json missing in %s; rescaffolding\", work_dir)\n                try:\n                    work_dir.mkdir(parents=True, exist_ok=True)\n                    self._scaffold(work_dir)\n                except OSError as exc:\n                    msg = f\"Failed to rescaffold server workspace at {work_dir}: {exc}\"\n                    raise RuntimeError(msg) from exc\n            if not config_path.exists():\n                if self._scaffold is not None:\n                    contents = sorted(p.name for p in work_dir.iterdir())\n                    msg = (\n                        f\"Rescaffolding {work_dir} did not produce langgraph.json \"\n                        f\"(directory contents: {contents}).\"\n                    )\n                else:\n                    msg = (\n                        f\"langgraph.json not found in {work_dir}. \"\n                        \"Call generate_langgraph_json() first.\"\n                    )\n                raise RuntimeError(msg)\n\n            if self.port == _EPHEMERAL_PORT:\n                self.port = _find_free_port(self.host)\n                logger.info(\n                    \"Using ephemeral port %d for langgraph dev server\", self.port","sourceCodeStart":919,"sourceCodeEnd":955,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/client/launch/server.py#L919-L955","documentation":"`_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.","triggerScenarios":"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.","commonSituations":"Running under a restricted user/CI container without write access to the cache/work directory, sandboxed environments blocking writes, or an immutable deployment filesystem.","solutions":["Ensure the process has write permission on the work_dir (chmod/chown or run as the right user)","Point the launcher at a writable workspace directory","Check the underlying `exc` text in the message for the precise OS cause (EACCES, EROFS, ENOSPC)","Pre-generate `langgraph.json` (call `generate_langgraph_json()`) so rescaffolding is never attempted"],"exampleFix":"// before\nwork_dir = Path(\"/opt/readonly/workspace\")  # not writable\n// after\nwork_dir = Path.home() / \".deepagents_code\" / \"workspace\"  # writable","handlingStrategy":"validation","validationCode":"import os\nwork_dir.mkdir(parents=True, exist_ok=True)\nif not os.access(work_dir, os.W_OK):\n    raise PermissionError(f\"{work_dir} is not writable\")","typeGuard":"def workspace_writable(path) -> bool:\n    import os\n    return path.is_dir() and os.access(path, os.W_OK)","tryCatchPattern":"try:\n    await server._start()\nexcept RuntimeError as e:\n    if str(e).startswith(\"Failed to rescaffold\"):\n        logger.error(\"rescaffold failed: %s\", e)\n        # switch to a writable dir and regenerate config\n        server.work_dir = writable_dir\n        generate_langgraph_json(server.work_dir)\n        await server._start()\n    else:\n        raise","preventionTips":["Check writability of the work dir before launching (os.access)","Pre-generate langgraph.json so rescaffolding never runs","Avoid read-only/immutable mounts for server workspaces","Run the launcher as a user with access to the workspace"],"tags":["filesystem","permissions","scaffold"],"backgroundTag":"permission-denied","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}