{"record":{"id":"e51eafe1983e58fb","repo":"openclaw/openclaw","slug":"computer-driver-error-tool-returned-invalid-st","errorCode":null,"errorMessage":"COMPUTER_DRIVER_ERROR: ${tool} returned invalid structuredContent","messagePattern":"COMPUTER_DRIVER_ERROR: (.+?) returned invalid structuredContent","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"extensions/cua-computer/src/commands.ts","lineNumber":145,"sourceCode":"      ? `COMPUTER_REFUSED_${result.errorCode}`\n      : \"COMPUTER_DRIVER_ERROR\";\n    throw new Error(`${code}: ${result.text || `${tool} failed`}`);\n  }\n  return result;\n}\n\nfunction structuredContent(result: CuaToolResult, tool: string): Record<string, unknown> {\n  assertToolSuccess(result, tool);\n  if (!result.structuredJson) {\n    throw new Error(`COMPUTER_DRIVER_ERROR: ${tool} returned no structuredContent`);\n  }\n  try {\n    const value: unknown = JSON.parse(result.structuredJson);\n    if (value && typeof value === \"object\" && !Array.isArray(value)) {\n      return value as Record<string, unknown>;\n    }\n  } catch {}\n  throw new Error(`COMPUTER_DRIVER_ERROR: ${tool} returned invalid structuredContent`);\n}\n\nfunction desktopGeometry(result: CuaToolResult): CuaDesktopGeometry {\n  const parsed = DesktopStateSchema.safeParse(structuredContent(result, \"get_desktop_state\"));\n  if (!parsed.success) {\n    throw new Error(\"COMPUTER_DRIVER_ERROR: invalid get_desktop_state geometry\");\n  }\n  return {\n    platform: parsed.data.platform,\n    display: parsed.data.display,\n    screenWidth: parsed.data.screen_width,\n    screenHeight: parsed.data.screen_height,\n    scaleFactor: parsed.data.scale_factor,\n    screenshotWidth: parsed.data.screenshot_width,\n    screenshotHeight: parsed.data.screenshot_height,\n  };\n}\n","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/openclaw/openclaw/blob/01804a75319da4b69c9ab98ceaa30477e22b8c0b/extensions/cua-computer/src/commands.ts#L127-L163","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the @trycua/cua-driver version matches the pinned 0.14.1 contract referenced in driver-client.ts","Log result.structuredJson before the parse to inspect what the driver actually returned","Check the native CUA driver process logs for errors during get_desktop_state or get_screen_size calls","Restart the CUA driver session — a stale or corrupted session can produce degenerate responses"],"exampleFix":"// Debug the raw driver response before it reaches structuredContent\nconst result = await driver.getDesktopState(signal);\nconsole.error('raw structuredJson:', result.structuredJson);\nconsole.error('raw isError:', result.isError, 'text:', result.text);\nconst geometry = desktopGeometry(result);","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isPlainObjectJson(value: string): boolean {\n  try {\n    const parsed: unknown = JSON.parse(value);\n    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed);\n  } catch {\n    return false;\n  }\n}","tryCatchPattern":"try {\n  const result = await driver.getDesktopState(signal);\n  const geometry = desktopGeometry(result);\n} catch (error) {\n  if (error instanceof Error && error.message.includes('returned invalid structuredContent')) {\n    // Driver returned non-object or non-JSON structured content\n    // Log result.structuredJson for diagnosis, then retry with fresh session\n  }\n  throw error;\n}","preventionTips":["Pin @trycua/cua-driver to the exact version tested with this plugin (0.14.1)","Check driver.isAvailable() before issuing commands that depend on structured content","Log raw CuaToolResult fields (structuredJson, images, isError, text) during development"],"tags":["cua-driver","json-parsing","structured-content","driver-protocol"],"backgroundTag":null,"analyzedSha":"01804a75319da4b69c9ab98ceaa30477e22b8c0b","analyzedAt":"2026-08-12T04:37:58.197Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}