openclaw/openclaw · error · WorkerProviderError

Crabbox inspect returned an invalid desktop home path

Error message

Crabbox inspect returned an invalid desktop home path

What it means

Thrown by resolveCrabboxWorkerHome() as a defensive guard when the computed home path (/root or /home/<user>) is not absolute or not in normalized form. Given SSH_USER_PATTERN is validated first, this branch is effectively unreachable under normal input; it exists to prevent path-traversal-style home paths from ever reaching the setup script if the username regex is ever widened.

Source

Thrown at extensions/crabbox/src/crabbox-worker-desktop-setup.ts:16

import path from "node:path";
import { WorkerProviderError, type WorkerDesktopEndpoint } from "openclaw/plugin-sdk/plugin-entry";

const CRABBOX_WORKER_BROWSER_PATH = "/usr/local/bin/openclaw-worker-browser";
const CRABBOX_WORKER_TERMINAL_PATH = "/usr/local/bin/openclaw-worker-terminal";
const CRABBOX_WORKER_BROWSER_CDP_PORT = 9222;

const SSH_USER_PATTERN = /^(?:root|[a-z_][a-z0-9_-]{0,31})$/u;

function resolveCrabboxWorkerHome(sshUser: string): string {
  if (!SSH_USER_PATTERN.test(sshUser)) {
    throw new WorkerProviderError("Crabbox inspect returned an invalid desktop SSH user");
  }
  const home = sshUser === "root" ? "/root" : `/home/${sshUser}`;
  if (!path.posix.isAbsolute(home) || path.posix.normalize(home) !== home) {
    throw new WorkerProviderError("Crabbox inspect returned an invalid desktop home path");
  }
  return home;
}

function browserLauncher(home: string, browserProfilePath: string): string[] {
  return [
    "#!/bin/bash",
    "set -euo pipefail",
    '[ "$#" -eq 0 ] || { echo "openclaw-worker-browser does not accept arguments" >&2; exit 64; }',
    '[ -r /var/lib/crabbox/desktop.env ] || { echo "Crabbox desktop environment is unavailable" >&2; exit 1; }',
    '[ -r /var/lib/crabbox/browser.env ] || { echo "Crabbox browser environment is unavailable" >&2; exit 1; }',
    ". /var/lib/crabbox/desktop.env",
    ". /var/lib/crabbox/browser.env",
    '[ "${CRABBOX_DESKTOP_ENV:-}" = "xfce" ] || { echo "Crabbox desktop environment is not XFCE" >&2; exit 1; }',
    '[ "${DISPLAY:-}" = ":99" ] || { echo "Crabbox XFCE display is not :99" >&2; exit 1; }',
    `export HOME=${home}`,
    "export DISPLAY",
    `export CRABBOX_BROWSER_PROFILE=${browserProfilePath}`,

View on GitHub (pinned to 01804a7531)

Solutions

1. Confirm the sshUser passed the SSH_USER_PATTERN check (see error 1285); if 1285 fired first, fix the username.
2. If you are editing this file and widened the regex, restore the strict pattern or add explicit traversal rejection before this check.
3. Report as a bug — this guard firing means the username regex contract is broken.

function isAbsoluteNormalizedPosixPath(p: string): boolean {
  return path.posix.isAbsolute(p) && path.posix.normalize(p) === p;
}

When it happens

Trigger: resolveCrabboxWorkerHome is called and, after the regex check, path.posix.isAbsolute(home)===false or path.posix.normalize(home)!==home. With the current regex this cannot occur for inputs that pass 1285; it would only fire if SSH_USER_PATTERN were loosened to allow traversal characters.

Common situations: Effectively unreachable today. Would surface only if a future edit to SSH_USER_PATTERN permits characters that break path normalization (e.g. '..' or symlinks), or if home derivation logic changes to incorporate user-controlled subpaths.

Related errors

• Crabbox inspect returned an invalid desktop SSH user
• Crabbox inspect returned invalid output
• Crabbox inspect returned an invalid ${field}
• Crabbox inspect returned invalid sshFallbackPorts
• Crabbox inspect returned invalid sshFallbackPorts: maximum 1

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