OpenHands/OpenHands · error

Failed to list workspace files

Error message

Failed to list workspace files

What it means

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.

Source

Thrown at src/hooks/query/use-workspace-files.ts:86

  const query = useQuery<string[]>({
    queryKey: [
      "workspace-files",
      conversationId,
      conversationUrl,
      sessionApiKey,
      workingDir,
    ],
    queryFn: async () => {
      const result = await AgentServerRuntimeService.executeCommand(
        conversationUrl,
        sessionApiKey,
        buildListCommand(),
        workingDir,
        30,
      );

      if (result.exit_code !== 0) {
        throw new Error(
          result.stderr?.trim() || "Failed to list workspace files",
        );
      }

      const lines = result.stdout
        .split(/\r?\n/)
        .map((line) => line.trim())
        .filter(Boolean)
        .map(normalizePath);

      // Defensive: keep results unique and bounded.
      return Array.from(new Set(lines)).slice(0, MAX_FILES);
    },
    enabled: enabled && runtimeIsReady && !!conversationId && !!workingDir,
    retry: false,
    staleTime: 1000 * 30,
    gcTime: 1000 * 60 * 5,
    meta: { disableToast: true },

View on GitHub (pinned to 500b4c533e)

Solutions

1. Open the conversation's workspace in a terminal tab and run `pwd && ls` to confirm the working_dir exists and is readable.
2. 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.
3. Restart the conversation with a valid working_dir if the path was removed.
4. On Docker deployments, confirm the workspace volume is mounted at the path the conversation reports as workspace.working_dir.

// Before listing, confirm workingDir exists and is readable
const probe = await AgentServerRuntimeService.executeCommand(conversationUrl, sessionApiKey, 'test -d "$PWD"', workingDir, 5);
if (probe.exit_code !== 0) { /* surface 'workspace not accessible' instead of generic find failure */ }

function isWorkspaceListingError(error: unknown): boolean {
  return error instanceof Error && (error.message === 'Failed to list workspace files' || /Failed to list workspace files/.test(error.message));
}

try {
  await queryClient.fetchQuery(workspaceFilesQuery);
} catch (error) {
  if (error instanceof Error && error.message.includes('workspace files')) {
    // show a 'workspace not accessible' affordance; offer to restart conversation
  } else throw error;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to read ${relativePath}: ${response.status}
• Invalid API key
• Invalid attachments
• OH_AGENT_SERVER_LOCAL_PATH is missing expected workspace pac

AI-assisted analysis of OpenHands/OpenHands@500b4c533e (2026-08-12). Data as JSON: /api/errors/77cbe6d5b1189d9f. Report an issue: GitHub.