{"record":{"id":"b852ca1ff25b404c","repo":"openclaw/openclaw","slug":"codex-remote-workspace-file-transfer-requires-node","errorCode":null,"errorMessage":"Codex remote workspace file transfer requires Node.js on the remote app-server host.","messagePattern":"Codex remote workspace file transfer requires Node\\.js on the remote app-server host\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"extensions/codex/src/app-server/remote-workspace-media.ts","lineNumber":151,"sourceCode":"            \"--\",\n            params.path,\n            String(params.maxBytes),\n            String(offset),\n            String(CODEX_REMOTE_MEDIA_CHUNK_BYTES),\n            ...(params.workspaceRoot ? [params.workspaceRoot] : []),\n          ],\n          // Prevent inherited Node preload hooks from changing the fixed reader.\n          env: { NODE_OPTIONS: null, NODE_PATH: null },\n          ...(timeoutMs === undefined ? {} : { timeoutMs }),\n        },\n        { signal: params.signal, timeoutMs },\n      );\n    } catch (error) {\n      if (\n        error instanceof Error &&\n        /failed to spawn|executable.*not found|\\bENOENT\\b/iu.test(error.message)\n      ) {\n        throw new Error(\n          \"Codex remote workspace file transfer requires Node.js on the remote app-server host.\",\n          { cause: error },\n        );\n      }\n      throw error;\n    }\n    if (!response || response.exitCode !== 0) {\n      const detail = typeof response?.stderr === \"string\" ? response.stderr.trim() : \"\";\n      throw new Error(\n        `Codex remote workspace artifact could not be read: ${params.path}${detail ? `: ${detail}` : \"\"}`,\n      );\n    }\n    if (\n      typeof response.stdout !== \"string\" ||\n      response.stdout.length > CODEX_REMOTE_COMMAND_DEFAULT_OUTPUT_BYTES\n    ) {\n      throw new Error(\"Codex remote workspace artifact exceeded the native command output cap.\");\n    }","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/openclaw/openclaw/blob/01804a75319da4b69c9ab98ceaa30477e22b8c0b/extensions/codex/src/app-server/remote-workspace-media.ts#L133-L169","documentation":"Thrown during readBoundedCodexRemoteWorkspaceFile when the command/exec call to run 'node -e ...' on the remote host fails to spawn, typically because Node.js is not installed or not on PATH on the remote app-server host. The error regex matches spawn failures including 'failed to spawn', 'executable not found', and 'ENOENT'. The original spawn error is attached as the cause.","triggerScenarios":"The remote Codex app-server host does not have Node.js installed, or 'node' is not on the system PATH in the context where the app-server runs command/exec. The error is matched from the caught exception's message using the regex /failed to spawn|executable.*not found|\\bENOENT\\b/iu.","commonSituations":"A remote SSH or container-based Codex setup where the app-server runs in an environment without Node.js. A minimal Docker image or Alpine container missing Node.js. A PATH configuration issue where the app-server's exec environment doesn't include the Node.js binary directory. A fresh remote host where dependencies haven't been installed.","solutions":["Install Node.js on the remote Codex app-server host (Node 22+ recommended).","Ensure 'node' is on the PATH in the environment where the Codex app-server executes commands — check the app-server service environment.","For Docker-based setups, use a base image that includes Node.js or add it to the Dockerfile.","Verify with 'ssh <host> node --version' that Node.js is accessible from the same context.","For container setups, ensure the app-server container has Node.js in its image."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Check Node.js availability on the remote host before attempting file transfer:\nasync function ensureRemoteNodeJs(client: CodexBoundedRemoteCommandClient): Promise<boolean> {\n  try {\n    const response = await client.request('command/exec', {\n      command: ['node', '--version'],\n      env: { NODE_OPTIONS: null, NODE_PATH: null },\n    }, { timeoutMs: 5000 });\n    return response.exitCode === 0 && typeof response.stdout === 'string';\n  } catch {\n    return false;\n  }\n}","typeGuard":"function isNodeMissingError(error: unknown): boolean {\n  return error instanceof Error &&\n    /failed to spawn|executable.*not found|\\bENOENT\\b/iu.test(error.message);\n}","tryCatchPattern":"try {\n  const file = await readBoundedCodexRemoteWorkspaceFile(params);\n} catch (error) {\n  if (error instanceof Error && error.message.includes('requires Node.js')) {\n    // Install Node.js on the remote host, then retry\n    throw new Error('Install Node.js 22+ on the remote Codex app-server host');\n  }\n  throw error;\n}","preventionTips":["Install Node.js (22+) on all remote Codex app-server hosts before using remote workspace features.","Ensure 'node' is on PATH in the app-server's exec environment.","For Docker setups, use a base image that includes Node.js.","Verify with 'node --version' from the same execution context."],"tags":["codex","remote-workspace","nodejs","environment","spawn","app-server"],"backgroundTag":null,"analyzedSha":"01804a75319da4b69c9ab98ceaa30477e22b8c0b","analyzedAt":"2026-08-12T04:37:58.197Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}