openclaw/openclaw · error

Crabbox inspect returned an invalid ${field}

Error message

Crabbox inspect returned an invalid ${field}

What it means

Thrown by inspectString() when a Crabbox inspect JSON field that must be a string (sshHost, host, sshUser, sshHostKey, or sshKey) is present but not of type string (e.g. a number, object, array, or null). The Crabbox provider treats the binary's inspect output as untrusted and validates every field; a non-string where a string endpoint field is expected means the lease contract is broken and cannot be used. The ${field} placeholder is interpolated with the offending field name.

Source

Thrown at extensions/crabbox/src/crabbox-worker-inspect.ts:107

    state,
    tailscaleEnabled,
    sshFallbackPorts,
    ...(awsInstanceProfileAttached !== undefined ? { awsInstanceProfileAttached } : {}),
    ...(host ? { host } : {}),
    ...(sshUser ? { sshUser } : {}),
    ...(sshHostKey ? { sshHostKey } : {}),
    ...(sshKey ? { sshKey } : {}),
    ...(sshPort ? { sshPort } : {}),
    ...(typeof value.ready === "boolean" ? { ready: value.ready } : {}),
  };
}

function inspectString(value: unknown, field: string): string | undefined {
  if (value === undefined) {
    return undefined;
  }
  if (typeof value !== "string") {
    throw new Error(`Crabbox inspect returned an invalid ${field}`);
  }
  return nonEmptyString(value);
}

function inspectPort(value: unknown): number | undefined {
  if (value === undefined || value === "") {
    return undefined;
  }
  return inspectRequiredPort(value, "sshPort");
}

function inspectFallbackPorts(value: unknown, primaryPort: number | undefined): number[] {
  if (value === undefined) {
    return [];
  }
  if (!Array.isArray(value)) {
    throw new Error("Crabbox inspect returned invalid sshFallbackPorts");
  }

View on GitHub (pinned to 01804a7531)

Solutions

  1. Re-run `crabbox inspect --provider <p> --id <id> --json` manually and inspect the raw JSON for the named field's value and type.
  2. Upgrade or downgrade the Crabbox binary to the version whose inspect contract matches this provider (check CHANGELOG for sshUser/sshHostKey type changes).
  3. If using a custom provider plugin in Crabbox, ensure its inspect implementation emits strings (or omits the field) for sshHost, host, sshUser, sshHostKey, sshKey.
  4. Destroy the malformed lease with `crabbox stop --provider <p> --id <id>` and provision a fresh one.
Defensive patterns

Strategy: try-catch

Type guard

function isInspectStringField(value: unknown): value is string {
  return typeof value === "string";
}

Try / catch

try {
  await provider.provision(profile, operationId);
} catch (error) {
  if (error instanceof Error && /Crabbox inspect returned an invalid (sshHost|host|sshUser|sshHostKey|sshKey)/.test(error.message)) {
    // malformed lease metadata — destroy and re-provision with a known-good Crabbox binary
  }
  throw error;
}

Prevention

When it happens

Trigger: Calling WorkerProvider.provision/inspect whose Crabbox binary emits JSON where one of sshHost, host, sshUser, sshHostKey, or sshKey is a non-string scalar (e.g. {"sshUser": 1001} or {"sshHostKey": null}). Triggered inside parseInspectJson at crabbox-worker-inspect.ts:79-84.

Common situations: Crabbox binary version mismatch where a newer/older CLI emits numeric UIDs or null for absent fields instead of strings; a buggy custom Crabbox provider plugin returning wrong types; corrupted lease metadata in the coordinator backend surfacing as JSON with unexpected scalar types.

Related errors

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