{"record":{"id":"77cbe6d5b1189d9f","repo":"OpenHands/OpenHands","slug":"failed-to-list-workspace-files","errorCode":null,"errorMessage":"Failed to list workspace files","messagePattern":"Failed to list workspace files","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/hooks/query/use-workspace-files.ts","lineNumber":86,"sourceCode":"  const query = useQuery<string[]>({\n    queryKey: [\n      \"workspace-files\",\n      conversationId,\n      conversationUrl,\n      sessionApiKey,\n      workingDir,\n    ],\n    queryFn: async () => {\n      const result = await AgentServerRuntimeService.executeCommand(\n        conversationUrl,\n        sessionApiKey,\n        buildListCommand(),\n        workingDir,\n        30,\n      );\n\n      if (result.exit_code !== 0) {\n        throw new Error(\n          result.stderr?.trim() || \"Failed to list workspace files\",\n        );\n      }\n\n      const lines = result.stdout\n        .split(/\\r?\\n/)\n        .map((line) => line.trim())\n        .filter(Boolean)\n        .map(normalizePath);\n\n      // Defensive: keep results unique and bounded.\n      return Array.from(new Set(lines)).slice(0, MAX_FILES);\n    },\n    enabled: enabled && runtimeIsReady && !!conversationId && !!workingDir,\n    retry: false,\n    staleTime: 1000 * 30,\n    gcTime: 1000 * 60 * 5,\n    meta: { disableToast: true },","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/OpenHands/OpenHands/blob/500b4c533e9393e44cb92894bcbb18438ef473b6/src/hooks/query/use-workspace-files.ts#L68-L104","documentation":"Fallback message thrown by useLocalWorkspaceFiles when the bash `find` command returns exit_code !== 0 and the command produced no trimmed stderr. The actual failure text would normally come from result.stderr; this generic string only appears when stderr is empty/whitespace so the user still sees a non-empty error. The query is marked retry: false, so a single failure surfaces immediately.","triggerScenarios":"Local backend executes buildListCommand() (a `find . \\( ... -prune \\) -o -type f -print` over the conversation's working_dir via AgentServerRuntimeService.executeCommand) and the process exits non-zero with empty stderr. Causes: working_dir does not exist on the agent-server filesystem; permissions deny traversal of the root; `find` binary missing in the sandbox; OOM kill of the subprocess.","commonSituations":"Conversation started with a working_dir that was later removed; Docker/sandbox volume not mounted at the configured path; agent-server running as a user without read access to the workspace; extremely deep directory tree exhausting file descriptors; SELinux/AppArmor denying find traversal.","solutions":["Open the conversation's workspace in a terminal tab and run `pwd && ls` to confirm the working_dir exists and is readable.","Check AgentServerRuntimeService.executeCommand's full result (stdout/stderr/exit_code) in a debug log — empty stderr with non-zero exit suggests a signal kill, not a normal error.","Restart the conversation with a valid working_dir if the path was removed.","On Docker deployments, confirm the workspace volume is mounted at the path the conversation reports as workspace.working_dir."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before listing, confirm workingDir exists and is readable\nconst probe = await AgentServerRuntimeService.executeCommand(conversationUrl, sessionApiKey, 'test -d \"$PWD\"', workingDir, 5);\nif (probe.exit_code !== 0) { /* surface 'workspace not accessible' instead of generic find failure */ }","typeGuard":"function isWorkspaceListingError(error: unknown): boolean {\n  return error instanceof Error && (error.message === 'Failed to list workspace files' || /Failed to list workspace files/.test(error.message));\n}","tryCatchPattern":"try {\n  await queryClient.fetchQuery(workspaceFilesQuery);\n} catch (error) {\n  if (error instanceof Error && error.message.includes('workspace files')) {\n    // show a 'workspace not accessible' affordance; offer to restart conversation\n  } else throw error;\n}","preventionTips":["Ensure the conversation's working_dir exists before the Files tab mounts.","In Docker deployments, confirm the workspace volume mount path matches working_dir.","Capture full stdout/stderr from executeCommand in debug logs — empty stderr with non-zero exit is unusual."],"tags":["workspace","files","local","bash"],"backgroundTag":null,"analyzedSha":"500b4c533e9393e44cb92894bcbb18438ef473b6","analyzedAt":"2026-08-12T10:07:46.034Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}