{"record":{"id":"0879e443d0fef4d9","repo":"Hmbown/CodeWhale","slug":"application-not-found-call-list-apps-for-exact-names-pids","errorCode":null,"errorMessage":"application not found — call list_apps for exact names/pids","messagePattern":"application not found — call list_apps for exact names/pids","errorType":"exception","errorClass":"ExecError","httpStatus":null,"severity":"error","filePath":"crates/tui/plugins/computer-use/src/backends/darwin.mjs","lineNumber":952,"sourceCode":"    },\n    list_apps: listApps,\n    set_window_frame: async ({ app_ref, window_id, frame } = {}) => {\n      if (!frame || !Number.isFinite(frame.x) || !Number.isFinite(frame.y) || !Number.isFinite(frame.w) || !Number.isFinite(frame.h) || frame.w <= 0 || frame.h <= 0) {\n        throw Object.assign(new ExecError(\"set_window_frame needs frame {x,y,w,h} with positive w/h\"), { code: \"bad_args\" });\n      }\n      if (!Number.isSafeInteger(window_id) || window_id < 0) {\n        throw Object.assign(new ExecError(\"set_window_frame needs window_id (a non-negative window index from list_windows)\"), { code: \"bad_args\" });\n      }\n      const r = await native(\"set_window_frame\", { app_ref, window_id, frame });\n      return { ...r, verified: r?.verified === true, note: r?.note ?? \"the after frame is the app's own readback; cross-check with list_windows before relying on it\" };\n    },\n    list_windows: listWindows,\n    open_application: openApplication,\n    get_app_state: async ({ app_ref, detail, depth, window_id, include_ocr = false, ocr_region } = {}) => {\n      const t0 = Date.now();\n      const t = await native(\"get_app_state\", { app_ref: app_ref === undefined ? state.inputApp ?? undefined : app_ref, detail, window_id });\n      if (process.env.CODEWHALE_CU_DEBUG_OBSERVE) console.error(`observe ${Date.now() - t0}ms elements=${t.elements?.length} truncated=${t.truncated}`);\n      if (!t.found) throw new ExecError(\"application not found — call list_apps for exact names/pids\");\n      if (include_ocr) {\n        // Resolve once through AX, then capture only that exact application's\n        // selected window. A changing foreground cannot redirect this image.\n        let raster;\n        try {\n          if (!Number.isSafeInteger(t.pid) || t.pid <= 0) throw new ExecError(\"The observed application did not provide an exact process identity for OCR\");\n          if ((await native(\"input_capabilities\"))?.window_ocr !== 1) throw new ExecError(\"The native helper needs an update for selected-window text recognition\");\n          // PNG here, against the JPEG default: this raster is fed to text\n          // recognition, not to a viewer, and lossless glyph edges are what\n          // Vision reads. A single window is small enough that the size the\n          // JPEG default exists to solve does not arise.\n          const ocrDir = path.join(recordingsDir(), \"captures\");\n          fs.mkdirSync(ocrDir, { recursive: true });\n          raster = await screenshot({\n            ...(ocr_region\n              ? { region: ocr_region }\n              : { app_ref: { pid: t.pid, ...(t.bundle_id ? { bundle_id: t.bundle_id } : {}) }, window_id }),\n            path: path.join(ocrDir, `ocr-${crypto.randomBytes(4).toString(\"hex\")}.png`),","sourceCodeStart":934,"sourceCodeEnd":970,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/plugins/computer-use/src/backends/darwin.mjs#L934-L970","documentation":"get_app_state resolves app_ref (falling back to the bound inputApp) through the native layer and returns a found flag; when the native lookup reports the application could not be found, the library throws this error directing the caller to list_apps for valid identities.","triggerScenarios":"Passing a pid of a process that has exited; a name/bundle_id that does not match any running app; omitting app_ref when no application has been bound via open_application; a 32-bit/removed app or permission-restricted process invisible to the accessibility API.","commonSituations":"Automating an app that crashed or was relaunched with a new pid between calls; app names differing from their display names; a freshly installed app not yet running; race between launching an app and querying its state.","solutions":["Call list_apps and use an exact name or pid from its output.","Re-fetch the pid after an app restart — pids change on relaunch.","If relying on the bound inputApp fallback, call open_application first.","Confirm the app is actually running (e.g. open_application can launch it by bundle_id)."],"exampleFix":"// before\nconst state = await backend.getAppState({ pid: 1234 }); // stale pid\n// after\nconst apps = await backend.listApps();\nconst app = apps.find(a => a.name === \"Safari\");\nconst state = await backend.getAppState({ pid: app.pid });","handlingStrategy":"validation","validationCode":"const apps = await backend.listApps();\nconst target = apps.find(a => a.name === appName || a.pid === pid);\nif (!target) throw new Error(`${appName} is not running`);","typeGuard":null,"tryCatchPattern":"try {\n  const st = await backend.getAppState({ app_ref });\n} catch (e) {\n  if (String(e.message).startsWith('application not found')) {\n    const apps = await backend.listApps(); // refresh identities and retry\n  } else throw e;\n}","preventionTips":["Never cache pids across app restarts; resolve via list_apps at use time.","If no app_ref is passed, ensure open_application was called first so the fallback binding exists.","Wait for an app to finish launching before querying its state."],"tags":["app-lookup","not-found","macos"],"backgroundTag":"entity-not-found","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-22T16:17:23.217Z"}