openclaw/openclaw · error · Error

Codex remote workspace file transfer requires Node.js on the

Error message

Codex remote workspace file transfer requires Node.js on the remote app-server host.

What it means

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.

Source

Thrown at extensions/codex/src/app-server/remote-workspace-media.ts:151

            "--",
            params.path,
            String(params.maxBytes),
            String(offset),
            String(CODEX_REMOTE_MEDIA_CHUNK_BYTES),
            ...(params.workspaceRoot ? [params.workspaceRoot] : []),
          ],
          // Prevent inherited Node preload hooks from changing the fixed reader.
          env: { NODE_OPTIONS: null, NODE_PATH: null },
          ...(timeoutMs === undefined ? {} : { timeoutMs }),
        },
        { signal: params.signal, timeoutMs },
      );
    } catch (error) {
      if (
        error instanceof Error &&
        /failed to spawn|executable.*not found|\bENOENT\b/iu.test(error.message)
      ) {
        throw new Error(
          "Codex remote workspace file transfer requires Node.js on the remote app-server host.",
          { cause: error },
        );
      }
      throw error;
    }
    if (!response || response.exitCode !== 0) {
      const detail = typeof response?.stderr === "string" ? response.stderr.trim() : "";
      throw new Error(
        `Codex remote workspace artifact could not be read: ${params.path}${detail ? `: ${detail}` : ""}`,
      );
    }
    if (
      typeof response.stdout !== "string" ||
      response.stdout.length > CODEX_REMOTE_COMMAND_DEFAULT_OUTPUT_BYTES
    ) {
      throw new Error("Codex remote workspace artifact exceeded the native command output cap.");
    }

View on GitHub (pinned to 01804a7531)

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.

Defensive patterns

Strategy: validation

Validate before calling

// Check Node.js availability on the remote host before attempting file transfer:
async function ensureRemoteNodeJs(client: CodexBoundedRemoteCommandClient): Promise<boolean> {
  try {
    const response = await client.request('command/exec', {
      command: ['node', '--version'],
      env: { NODE_OPTIONS: null, NODE_PATH: null },
    }, { timeoutMs: 5000 });
    return response.exitCode === 0 && typeof response.stdout === 'string';
  } catch {
    return false;
  }
}

Type guard

function isNodeMissingError(error: unknown): boolean {
  return error instanceof Error &&
    /failed to spawn|executable.*not found|\bENOENT\b/iu.test(error.message);
}

Try / catch

try {
  const file = await readBoundedCodexRemoteWorkspaceFile(params);
} catch (error) {
  if (error instanceof Error && error.message.includes('requires Node.js')) {
    // Install Node.js on the remote host, then retry
    throw new Error('Install Node.js 22+ on the remote Codex app-server host');
  }
  throw error;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of openclaw/openclaw@01804a7531 (2026-08-12). Data as JSON: /api/errors/b852ca1ff25b404c. Report an issue: GitHub.