Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(files): handle vanished folders on list requests instead of returning 500 (#20892)

cielebc4460daa52
diff --git a/internal/handler/file.go b/internal/handler/file.go
index b711992e6b..64260f4dcd 100644
--- a/internal/handler/file.go
+++ b/internal/handler/file.go
@@ -46,6 +46,11 @@ func respondFileServiceError(c *gin.Context, err error) {
if respondPermissionErrorIf(c, err, true) {
return
}
+ var codedErr *common.CodedError
+ if errors.As(err, &codedErr) {
+ common.ErrorWithCode(c, codedErr.Code, codedErr.Message)
+ return
+ }
jsonInternalError(c, err)
}
diff --git a/internal/service/file/file_folder.go b/internal/service/file/file_folder.go
index aee22e9e69..87e71307ce 100644
--- a/internal/service/file/file_folder.go
+++ b/internal/service/file/file_folder.go
@@ -11,6 +11,8 @@ import (
"ragflow/internal/storage"
"ragflow/internal/utility"
"strings"
+
+ "gorm.io/gorm"
)
// GetRootFolder gets or creates root folder for tenant
@@ -25,6 +27,16 @@ func (s *FileService) GetRootFolder(ctx context.Context, tenantID string) (map[s
return s.toFileResponse(file), nil
}
+// lookupError classifies a file lookup failure: a missing row is a client-facing
+// not-found (CodeNotFound), while any other error (connection loss, timeout,
+// etc.) is returned unchanged so handlers keep reporting it as a server error.
+func lookupError(err error, message string) error {
+ if errors.Is(err, gorm.ErrRecordNotFound) {
+ return common.NewCodedError(common.CodeNotFound, message)
+ }
+ return err
+}
+
// ListFiles lists files by parent folder ID (matching Python /files endpoint)
// This method includes init_dataset_docs initialization when parent_id is empty
func (s *FileService) ListFiles(ctx context.Context, tenantID, pfID string, page, pageSize int, terms []dao.OrderTerm, keywords string) (*ListFilesResponse, error) {
@@ -77,7 +89,7 @@ func (s *FileService) listFiles(ctx context.Context, userID, tenantID, pfID stri
// Check if parent folder exists
folder, err := s.fileDAO.GetByID(ctx, dao.DB, pfID)
if err != nil {
- return nil, fmt.Errorf("folder not found")
+ return nil, lookupError(err, "folder not found")
}
if folder.Type != FileTypeFolder {
return nil, permission.ErrResourceNotFound
@@ -261,7 +273,7 @@ func (s *FileService) GetParentFolder(ctx context.Context, userID, fileID string
// Get file
file, err := s.fileDAO.GetByID(ctx, dao.DB, fileID)
if err != nil {
- return nil, err
+ return nil, lookupError(err, "file or folder not found")
}
// Permission check
@@ -305,7 +317,7 @@ func (s *FileService) getAllParentFolders(ctx context.Context, userID, tenantID,
// Get file
file, err := s.fileDAO.GetByID(ctx, dao.DB, fileID)
if err != nil {
- return nil, err
+ return nil, lookupError(err, "file or folder not found")
}
if tenantID != "" && file.TenantID != tenantID {
return nil, permission.ErrResourceNotFound
diff --git a/internal/service/file/file_folder_test.go b/internal/service/file/file_folder_test.go
index f56cf90dea..f1572dd324 100644
--- a/internal/service/file/file_folder_test.go
+++ b/internal/service/file/file_folder_test.go
@@ -6,6 +6,7 @@ import (
"strings"
"testing"
+ "ragflow/internal/common"
"ragflow/internal/dao"
"ragflow/internal/entity"
"ragflow/internal/permission"
@@ -213,6 +214,65 @@ func insertFolderTestFile(t *testing.T, id, parentID, name string) {
}
}
+func TestFileService_ListFilesMissingParentReturnsNotFound(t *testing.T) {
+ setupFolderTestDB(t)
+
+ root := &entity.File{ID: "root-1", ParentID: "root-1", TenantID: "tenant-1", Name: "/", Type: FileTypeFolder}
+ if err := dao.DB.Create(root).Error; err != nil {
+ t.Fatalf("seed root: %v", err)
+ }
+
+ svc := testFileService()
+ _, err := svc.ListFiles(context.Background(), "tenant-1", "missing-folder", 1, 10, nil, "")
+ var coded *common.CodedError
+ if !errors.As(err, &coded) || coded.Code != common.CodeNotFound {
+ t.Fatalf("ListFiles error = %v, want CodeNotFound CodedError", err)
+ }
+}
+
+func TestFileService_AncestryMissingIDReturnsNotFound(t *testing.T) {
+ setupFolderTestDB(t)
+
+ svc := testFileService()
+ ctx := context.Background()
+ for name, call := range map[string]func() error{
+ "GetParentFolder": func() error { _, err := svc.GetParentFolder(ctx, "user-1", "missing-file"); return err },
+ "GetAllParentFolders": func() error { _, err := svc.GetAllParentFolders(ctx, "user-1", "missing-file"); return err },
+ } {
+ var coded *common.CodedError
+ if err := call(); !errors.As(err, &coded) || coded.Code != common.CodeNotFound {
+ t.Fatalf("%s error = %v, want CodeNotFound CodedError", name, err)
+ }
+ }
+}
+
+func TestFileService_DatabaseErrorIsNotReportedAsNotFound(t *testing.T) {
+ db := setupFolderTestDB(t)
+
+ sqlDB, err := db.DB()
+ if err != nil {
+ t.Fatalf("get underlying sql db: %v", err)
+ }
+ if err := sqlDB.Close(); err != nil {
+ t.Fatalf("close sql db: %v", err)
+ }
+
+ svc := testFileService()
+ ctx := context.Background()
+ for name, call := range map[string]func() error{
+ "ListFiles": func() error { _, err := svc.ListFiles(ctx, "tenant-1", "any", 1, 10, nil, ""); return err },
+ "GetParentFolder": func() error { _, err := svc.GetParentFolder(ctx, "user-1", "any"); return err },
+ "GetAllParentFolders": func() error { _, err := svc.GetAllParentFolders(ctx, "user-1", "any"); return err },
+ } {
+ coded := (*common.CodedError)(nil)
+ if err := call(); err == nil {
+ t.Fatalf("%s: expected a database error, got nil", name)
+ } else if errors.As(err, &coded) {
+ t.Fatalf("%s error = %v, must not be reported as CodeNotFound", name, err)
+ }
+ }
+}
+
func TestFileService_AncestryRejectsUnauthorized(t *testing.T) {
setupFolderTestDB(t)
insertFolderTestFile(t, "file-1", "folder-1", "file.pdf")
diff --git a/web/src/hooks/__tests__/use-file-list-not-found.test.tsx b/web/src/hooks/__tests__/use-file-list-not-found.test.tsx
new file mode 100644
index 0000000000..1960615d9a
--- /dev/null
+++ b/web/src/hooks/__tests__/use-file-list-not-found.test.tsx
@@ -0,0 +1,102 @@
+import fileManagerService from '@/services/file-manager-service';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { renderHook, waitFor } from '@testing-library/react';
+import React from 'react';
+
+import { useFetchFileList } from '../use-file-request';
+
+jest.mock('@/services/file-manager-service', () => ({
+ __esModule: true,
+ default: { listFile: jest.fn() },
+}));
+
+jest.mock('@/components/ui/message', () => ({
+ __esModule: true,
+ default: { success: jest.fn(), error: jest.fn() },
+}));
+
+// @/utils/request pulls in the legacy i18n/locales graph that touches
+// import.meta.env, which jest cannot transform; the list query never calls it
+// directly, so stub the module.
+jest.mock('@/utils/request', () => ({ __esModule: true, default: jest.fn() }));
+
+jest.mock('@/utils/file-util', () => ({ downloadFileFromBlob: jest.fn() }));
+
+jest.mock('react-i18next', () => ({
+ useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+jest.mock('react-router', () => ({
+ useSearchParams: jest.fn(() => [
+ new URLSearchParams('folderId=deleted-folder'),
+ ]),
+}));
+
+jest.mock('ahooks', () => ({ useDebounce: (value: unknown) => value }));
+
+jest.mock('@/hooks/logic-hooks', () => ({
+ useGetPaginationWithRouter: jest.fn(() => ({
+ pagination: { current: 1, pageSize: 10 },
+ setPagination: jest.fn(),
+ })),
+ useHandleSearchChange: jest.fn(() => ({
+ searchString: '',
+ setSearchString: jest.fn(),
+ handleInputChange: jest.fn(),
+ })),
+}));
+
+jest.mock('@/hooks/route-hook', () => ({
+ useSetPaginationParams: jest.fn(() => jest.fn()),
+}));
+
+const mockListFile = jest.mocked(fileManagerService.listFile);
+
+function makeWrapper() {
+ const queryClient = new QueryClient({
+ defaultOptions: {
+ queries: { retry: false },
+ mutations: { retry: false },
+ },
+ });
+ return (props: { children: any }) =>
+ React.createElement(
+ QueryClientProvider,
+ { client: queryClient },
+ props.children,
+ );
+}
+
+describe('useFetchFileList missing folder', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('flags folderNotFound when the folder listing returns 404', async () => {
+ mockListFile.mockResolvedValue({ data: { code: 404 } } as never);
+
+ const { result } = renderHook(() => useFetchFileList(), {
+ wrapper: makeWrapper(),
+ });
+
+ await waitFor(() => expect(result.current.folderNotFound).toBe(true));
+ expect(mockListFile).toHaveBeenCalledWith(
+ expect.objectContaining({ parent_id: 'deleted-folder' }),
+ );
+ });
+
+ it('does not flag folderNotFound on a successful listing', async () => {
+ mockListFile.mockResolvedValue({
+ data: { code: 0, data: { files: [], total: 7 } },
+ } as never);
+
+ const { result } = renderHook(() => useFetchFileList(), {
+ wrapper: makeWrapper(),
+ });
+
+ // initialData.total is 0, so a distinct total proves the successful
+ // response was applied before the flag assertion runs.
+ await waitFor(() => expect(result.current.total).toBe(7));
+ expect(result.current.folderNotFound).toBe(false);
+ });
+});
diff --git a/web/src/hooks/use-file-request.ts b/web/src/hooks/use-file-request.ts
index b0aba7d885..8f1b4bab47 100644
--- a/web/src/hooks/use-file-request.ts
+++ b/web/src/hooks/use-file-request.ts
@@ -225,6 +225,19 @@ export const useFetchFileList = () => {
page: pagination.current,
});
+ // The requested folder was removed (e.g. by moving an ancestor into
+ // another folder, which recreates the subtree under new IDs). Surface
+ // it as an empty result flagged for redirect instead of an error, so
+ // React Query does not retry a folder that will never come back.
+ if (data?.code === 404) {
+ return {
+ files: [],
+ parent_folder: {} as IFolder,
+ total: 0,
+ folderNotFound: true,
+ };
+ }
+
return data?.data;
},
});
@@ -245,6 +258,7 @@ export const useFetchFileList = () => {
pagination: { ...pagination, total: data?.total },
setPagination,
loading,
+ folderNotFound: data?.folderNotFound === true,
};
};
diff --git a/web/src/interfaces/database/file-manager.ts b/web/src/interfaces/database/file-manager.ts
index 1a58e98bba..37f7d58560 100644
--- a/web/src/interfaces/database/file-manager.ts
+++ b/web/src/interfaces/database/file-manager.ts
@@ -36,4 +36,7 @@ export type IFetchFileListResult = {
files: IFile[];
parent_folder: IFolder;
total: number;
+ // Set by the file-list hook when the requested folder no longer exists so
+ // the page can redirect to the root folder instead of rendering an error.
+ folderNotFound?: boolean;
};
diff --git a/web/src/pages/files/index.tsx b/web/src/pages/files/index.tsx
index bc61d46a95..2dda17857d 100644
--- a/web/src/pages/files/index.tsx
+++ b/web/src/pages/files/index.tsx
@@ -15,6 +15,7 @@ import { useClearSelectionOnPageChange } from '@/hooks/logic-hooks/use-clear-sel
import { useRowSelection } from '@/hooks/logic-hooks/use-row-selection';
import { useFetchFileList } from '@/hooks/use-file-request';
import { LucidePlus } from 'lucide-react';
+import { useEffect } from 'react';
import { useTranslation } from 'react-i18next';
import { CreateFolderDialog } from './create-folder-dialog';
import { FileBreadcrumb } from './file-breadcrumb';
@@ -27,7 +28,10 @@ import { MoveDialog } from './move-dialog';
import { useBulkOperateFile } from './use-bulk-operate-file';
import { useHandleCreateFolder } from './use-create-folder';
import { useHandleMoveFile } from './use-move-file';
-import { useSelectBreadcrumbItems } from './use-navigate-to-folder';
+import {
+ useNavigateToOtherFolder,
+ useSelectBreadcrumbItems,
+} from './use-navigate-to-folder';
import { useHandleUploadFile } from './use-upload-file';
export default function Files() {
@@ -57,8 +61,20 @@ export default function Files() {
searchString,
setSearchString,
handleInputChange,
+ folderNotFound,
} = useFetchFileList();
+ const navigateToOtherFolder = useNavigateToOtherFolder();
+
+ // The folder currently open was removed (e.g. an ancestor was moved into
+ // another folder). Send the user back to the root instead of showing an
+ // error for a listing that no longer exists.
+ useEffect(() => {
+ if (folderNotFound) {
+ navigateToOtherFolder('');
+ }
+ }, [folderNotFound, navigateToOtherFolder]);
+
const {
rowSelection,
setRowSelection,
diff --git a/web/src/services/file-manager-service.ts b/web/src/services/file-manager-service.ts
index 00dcb0e304..ede05c47d4 100644
--- a/web/src/services/file-manager-service.ts
+++ b/web/src/services/file-manager-service.ts
@@ -36,6 +36,9 @@ const methods = {
listFile: {
url: listFile,
method: 'get',
+ // A 404 means the folder being listed no longer exists; the page handles
+ // it by redirecting to the root folder instead of showing a toast.
+ skipErrorCodes: [404],
},
removeFile: {
url: removeFile,
@@ -48,6 +51,9 @@ const methods = {
getAllParentFolder: {
url: getAllParentFolder,
method: 'get',
+ // Same vanished-folder case as listFile: the ancestors of a deleted
+ // folder must not surface a global error.
+ skipErrorCodes: [404],
},
createFolder: {
url: createFolder,
diff --git a/web/src/utils/request.ts b/web/src/utils/request.ts
index 970ae4b8ad..bcdb40f419 100644
--- a/web/src/utils/request.ts
+++ b/web/src/utils/request.ts
@@ -160,6 +160,13 @@ request.interceptors.response.use(async (response: Response, options) => {
return response;
}
+ // Per-request opt-out for response codes that the caller handles itself
+ // (e.g. a vanished folder on a list request is a normal navigation case,
+ // not a user-facing error).
+ const skipErrorCodes = (options as any)?.skipErrorCodes as
+ | number[]
+ | undefined;
+
const data: ResponseType = await response?.clone()?.json();
// Update LLM list cache when fetching my_llm or llm_list
@@ -185,7 +192,7 @@ request.interceptors.response.use(async (response: Response, options) => {
}
authorizationUtil.removeAll();
redirectToLogin();
- } else if (data?.code !== 0) {
+ } else if (data?.code !== 0 && !skipErrorCodes?.includes(data?.code)) {
notification.error({
message: `${i18n.t('message.hint')} : ${data?.code}`,
description: data?.message,