openclaw/openclaw · error · Error

COMPUTER_DRIVER_ERROR: ${tool} returned invalid structuredCo

Error message

COMPUTER_DRIVER_ERROR: ${tool} returned invalid structuredContent

What it means

Thrown by structuredContent() when the CUA driver returns a structuredJson field that either fails JSON.parse or parses to a non-object value (array, primitive, null). The function requires a JSON object to extract structured tool output (desktop state, screen size). The catch block silently swallows parse errors, so both malformed JSON and valid-but-wrong-type JSON surface as the same message.

Source

Thrown at extensions/cua-computer/src/commands.ts:145

      ? `COMPUTER_REFUSED_${result.errorCode}`
      : "COMPUTER_DRIVER_ERROR";
    throw new Error(`${code}: ${result.text || `${tool} failed`}`);
  }
  return result;
}

function structuredContent(result: CuaToolResult, tool: string): Record<string, unknown> {
  assertToolSuccess(result, tool);
  if (!result.structuredJson) {
    throw new Error(`COMPUTER_DRIVER_ERROR: ${tool} returned no structuredContent`);
  }
  try {
    const value: unknown = JSON.parse(result.structuredJson);
    if (value && typeof value === "object" && !Array.isArray(value)) {
      return value as Record<string, unknown>;
    }
  } catch {}
  throw new Error(`COMPUTER_DRIVER_ERROR: ${tool} returned invalid structuredContent`);
}

function desktopGeometry(result: CuaToolResult): CuaDesktopGeometry {
  const parsed = DesktopStateSchema.safeParse(structuredContent(result, "get_desktop_state"));
  if (!parsed.success) {
    throw new Error("COMPUTER_DRIVER_ERROR: invalid get_desktop_state geometry");
  }
  return {
    platform: parsed.data.platform,
    display: parsed.data.display,
    screenWidth: parsed.data.screen_width,
    screenHeight: parsed.data.screen_height,
    scaleFactor: parsed.data.scale_factor,
    screenshotWidth: parsed.data.screenshot_width,
    screenshotHeight: parsed.data.screenshot_height,
  };
}

View on GitHub (pinned to 01804a7531)

Solutions

1. Verify the @trycua/cua-driver version matches the pinned 0.14.1 contract referenced in driver-client.ts
2. Log result.structuredJson before the parse to inspect what the driver actually returned
3. Check the native CUA driver process logs for errors during get_desktop_state or get_screen_size calls
4. Restart the CUA driver session — a stale or corrupted session can produce degenerate responses

Example fix

// Debug the raw driver response before it reaches structuredContent
const result = await driver.getDesktopState(signal);
console.error('raw structuredJson:', result.structuredJson);
console.error('raw isError:', result.isError, 'text:', result.text);
const geometry = desktopGeometry(result);

function isPlainObjectJson(value: string): boolean {
  try {
    const parsed: unknown = JSON.parse(value);
    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed);
  } catch {
    return false;
  }
}

try {
  const result = await driver.getDesktopState(signal);
  const geometry = desktopGeometry(result);
} catch (error) {
  if (error instanceof Error && error.message.includes('returned invalid structuredContent')) {
    // Driver returned non-object or non-JSON structured content
    // Log result.structuredJson for diagnosis, then retry with fresh session
  }
  throw error;
}

When it happens

Trigger: Called indirectly via desktopGeometry() (get_desktop_state) or screenSize() (get_screen_size) during screen.snapshot or computer.act. Fires when driver.getDesktopState() or driver.getScreenSize() returns a CuaToolResult whose structuredJson is a JSON array, string, number, or syntactically invalid JSON.

Common situations: CUA driver version mismatch where the SDK contract for structured content changed. A driver crash or partial response that leaves structuredJson populated with an error string instead of structured data. A native FFI boundary serialization bug producing truncated or double-encoded JSON.

Related errors

• Chrome MCP snapshot response was missing structured snapshot
• Crabbox inspect returned an invalid ${field}
• Crabbox inspect returned invalid sshFallbackPorts
• Crabbox config show returned invalid JSON
• Crabbox config show returned an invalid AWS instance profile

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