fix(docker): enhance error handling and user feedback for Docker service unavailability

frontend/src/hooks/__tests__/useDocker.test.tsx

@@ -123,6 +123,35 @@ describe('useDocker', () => {
     expect(result.current.containers).toEqual([]);
   });
 
+  it('extracts details from 503 service unavailable error', async () => {
+    const mockError = {
+      response: {
+        status: 503,
+        data: {
+          error: 'Docker daemon unavailable',
+          details: 'Cannot connect to Docker. Please ensure Docker is running and the socket is accessible (e.g., /var/run/docker.sock is mounted).'
+        }
+      }
+    };
+    vi.mocked(dockerApi.listContainers).mockRejectedValue(mockError);
+
+    const { result } = renderHook(() => useDocker('local'), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(
+      () => {
+        expect(result.current.isLoading).toBe(false);
+      },
+      { timeout: 3000 }
+    );
+
+    // Verify error message includes the details
+    expect(result.current.error).toBeTruthy();
+    const errorMessage = (result.current.error as Error)?.message;
+    expect(errorMessage).toContain('Docker is running');
+  });
+
   it('provides refetch function', async () => {
     vi.mocked(dockerApi.listContainers).mockResolvedValue(mockContainers);
 

frontend/src/hooks/useDocker.ts

@@ -9,7 +9,19 @@ export function useDocker(host?: string | null, serverId?: string | null) {
     refetch,
   } = useQuery({
     queryKey: ['docker-containers', host, serverId],
-    queryFn: () => dockerApi.listContainers(host || undefined, serverId || undefined),
+    queryFn: async () => {
+      try {
+        return await dockerApi.listContainers(host || undefined, serverId || undefined)
+      } catch (err: any) {
+        // Extract helpful error message from response
+        if (err.response?.status === 503) {
+          const details = err.response?.data?.details
+          const message = details || 'Docker service unavailable. Check that Docker is running.'
+          throw new Error(message)
+        }
+        throw err
+      }
+    },
     enabled: Boolean(host) || Boolean(serverId),
     retry: 1, // Don't retry too much if docker is not available
   })