Skip to content

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

fix(document): reject config edits while document is parsing or scheduled (#18804)

xugangqiang193595881300
diff --git a/internal/entity/dataset.go b/internal/entity/dataset.go
index 101662aeb0..26826bfe9d 100644
--- a/internal/entity/dataset.go
+++ b/internal/entity/dataset.go
@@ -72,6 +72,19 @@ const (
TaskStatusSchedule TaskStatus = "5"
)
+// DocumentModifiableStatuses are the run statuses in which a document's
+// configuration (parser config, chunk method, pipeline id, name, enabled
+// flag, ...) may be edited via UpdateDatasetDocument. Documents that are
+// running ("1") or scheduled ("5") must not be edited — the in-flight parser
+// would race with the config change and the document can get stuck and become
+// undeletable.
+var DocumentModifiableStatuses = map[TaskStatus]bool{
+ TaskStatusUnstart: true,
+ TaskStatusCancel: true,
+ TaskStatusDone: true,
+ TaskStatusFail: true,
+}
+
// PipelineTaskType represents the type of pipeline task
type PipelineTaskType string
diff --git a/internal/service/document/document_dataset_update.go b/internal/service/document/document_dataset_update.go
index a5f19008f5..72e933e65c 100644
--- a/internal/service/document/document_dataset_update.go
+++ b/internal/service/document/document_dataset_update.go
@@ -237,10 +237,34 @@ func (s *DocumentService) UpdateDatasetDocument(ctx context.Context, userID, dat
return s.toUpdateDatasetDocumentResponse(updatedDoc, metaFields), common.CodeSuccess, nil
}
+// validateDocumentModifiable rejects configuration edits while the document is
+// actively parsing or scheduled. Editing a document that is mid-parse races
+// with the running worker and can leave the document stuck and undeletable.
+func (s *DocumentService) validateDocumentModifiable(doc *entity.Document) (common.ErrorCode, error) {
+ if doc.Run != nil {
+ run := entity.TaskStatus(*doc.Run)
+ if !entity.DocumentModifiableStatuses[run] {
+ return common.CodeDataError, fmt.Errorf(
+ "document is currently %q and cannot be modified; stop parsing or wait for it to finish before updating its configuration", run)
+ }
+ }
+ return common.CodeSuccess, nil
+}
+
func (s *DocumentService) validateDatasetDocumentUpdate(ctx context.Context, datasetID, documentID, userID string, doc *entity.Document, req *UpdateDatasetDocumentRequest, present map[string]bool) (common.ErrorCode, error) {
if req == nil {
return common.CodeDataError, errors.New("invalid request payload")
}
+
+ // Reject any configuration edit while the document is parsing or scheduled.
+ // This guard is field-agnostic: every editable field (name, parser_config,
+ // chunk_method, pipeline_id, enabled, meta_fields) is blocked so the
+ // in-flight parser never reads a config that changed underneath it.
+ if len(present) > 0 {
+ if code, err := s.validateDocumentModifiable(doc); err != nil {
+ return code, err
+ }
+ }
if present["chunk_count"] && req.ChunkCount != nil && *req.ChunkCount != 0 && *req.ChunkCount != doc.ChunkNum {
return common.CodeDataError, errors.New("can't change `chunk_count`")
}
diff --git a/internal/service/document/document_modify_guard_test.go b/internal/service/document/document_modify_guard_test.go
new file mode 100644
index 0000000000..0073739420
--- /dev/null
+++ b/internal/service/document/document_modify_guard_test.go
@@ -0,0 +1,229 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package document
+
+import (
+ "strings"
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/entity"
+)
+
+// TestValidateDocumentModifiable_RunStatuses pins the allowed/disallowed run
+// statuses for editing a document via UpdateDatasetDocument. RUNNING ("1") and
+// SCHEDULE ("5") must be rejected; UNSTART/CANCEL/DONE/FAIL may be edited.
+// A nil Run (gorm default "0" UNSTART) is treated as editable.
+func TestValidateDocumentModifiable_RunStatuses(t *testing.T) {
+ cases := []struct {
+ name string
+ run *string
+ wantCode common.ErrorCode
+ wantErr bool
+ }{
+ {"nil run defaults to unstart", nil, common.CodeSuccess, false},
+ {"unstart editable", sptr(string(entity.TaskStatusUnstart)), common.CodeSuccess, false},
+ {"cancel editable", sptr(string(entity.TaskStatusCancel)), common.CodeSuccess, false},
+ {"done editable", sptr(string(entity.TaskStatusDone)), common.CodeSuccess, false},
+ {"fail editable", sptr(string(entity.TaskStatusFail)), common.CodeSuccess, false},
+ {"running rejected", sptr(string(entity.TaskStatusRunning)), common.CodeDataError, true},
+ {"schedule rejected", sptr(string(entity.TaskStatusSchedule)), common.CodeDataError, true},
+ }
+
+ svc := &DocumentService{}
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ doc := &entity.Document{Run: tc.run}
+ code, err := svc.validateDocumentModifiable(doc)
+ if tc.wantErr {
+ if err == nil {
+ t.Fatalf("expected error, got nil")
+ }
+ if code != tc.wantCode {
+ t.Fatalf("code = %v, want %v", code, tc.wantCode)
+ }
+ if !strings.Contains(err.Error(), "cannot be modified") {
+ t.Fatalf("err = %q missing sentinel phrase", err.Error())
+ }
+ return
+ }
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ if code != tc.wantCode {
+ t.Fatalf("code = %v, want %v", code, tc.wantCode)
+ }
+ })
+ }
+}
+
+// updateDatasetDocumentRejected asserts that editing a document in the given
+// run status with the supplied request is rejected by the run-state guard.
+func updateDatasetDocumentRejected(t *testing.T, run string, req *UpdateDatasetDocumentRequest, present map[string]bool) {
+ t.Helper()
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertTestDocWithRun(t, "doc-1", "kb-1", run, 0, 0)
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ _, code, err := svc.UpdateDatasetDocument(ctx, "tenant-1", "kb-1", "doc-1", req, present)
+ if err == nil {
+ t.Fatalf("expected run-state rejection, got nil error (code=%v)", code)
+ }
+ if code != common.CodeDataError {
+ t.Fatalf("code = %v, want %v", code, common.CodeDataError)
+ }
+ if !strings.Contains(err.Error(), "cannot be modified") {
+ t.Fatalf("err = %q missing sentinel phrase", err.Error())
+ }
+}
+
+// updateDatasetDocumentAllowed asserts that editing a document in an editable
+// run status with the supplied request is NOT blocked by the run-state guard
+// (it may still fail later validation, but not with the run-state error).
+func updateDatasetDocumentAllowed(t *testing.T, run string, req *UpdateDatasetDocumentRequest, present map[string]bool) {
+ t.Helper()
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertTestDocWithRun(t, "doc-1", "kb-1", run, 0, 0)
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ _, code, err := svc.UpdateDatasetDocument(ctx, "tenant-1", "kb-1", "doc-1", req, present)
+ if err != nil && strings.Contains(err.Error(), "cannot be modified") {
+ t.Fatalf("editable doc was wrongly rejected: %v", err)
+ }
+ if err != nil {
+ t.Logf("non-run-state error (acceptable): code=%v err=%v", code, err)
+ }
+}
+
+func TestUpdateDatasetDocumentRejectsRunningParserConfig(t *testing.T) {
+ updateDatasetDocumentRejected(t, string(entity.TaskStatusRunning),
+ &UpdateDatasetDocumentRequest{ParserConfig: map[string]any{"chunk_token_num": float64(128)}},
+ map[string]bool{"parser_config": true})
+}
+
+func TestUpdateDatasetDocumentRejectsRunningChunkMethod(t *testing.T) {
+ cm := "naive"
+ updateDatasetDocumentRejected(t, string(entity.TaskStatusRunning),
+ &UpdateDatasetDocumentRequest{ChunkMethod: &cm},
+ map[string]bool{"chunk_method": true})
+}
+
+func TestUpdateDatasetDocumentRejectsRunningRename(t *testing.T) {
+ name := "renamed.txt"
+ updateDatasetDocumentRejected(t, string(entity.TaskStatusRunning),
+ &UpdateDatasetDocumentRequest{Name: &name},
+ map[string]bool{"name": true})
+}
+
+func TestUpdateDatasetDocumentRejectsRunningEnabled(t *testing.T) {
+ enabled := 0
+ updateDatasetDocumentRejected(t, string(entity.TaskStatusRunning),
+ &UpdateDatasetDocumentRequest{Enabled: &enabled},
+ map[string]bool{"enabled": true})
+}
+
+func TestUpdateDatasetDocumentRejectsScheduledRename(t *testing.T) {
+ name := "renamed.txt"
+ updateDatasetDocumentRejected(t, string(entity.TaskStatusSchedule),
+ &UpdateDatasetDocumentRequest{Name: &name},
+ map[string]bool{"name": true})
+}
+
+func TestUpdateDatasetDocumentAllowsDoneEnabled(t *testing.T) {
+ enabled := 0
+ updateDatasetDocumentAllowed(t, string(entity.TaskStatusDone),
+ &UpdateDatasetDocumentRequest{Enabled: &enabled},
+ map[string]bool{"enabled": true})
+}
+
+func TestUpdateDatasetDocumentAllowsCancelEnabled(t *testing.T) {
+ enabled := 0
+ updateDatasetDocumentAllowed(t, string(entity.TaskStatusCancel),
+ &UpdateDatasetDocumentRequest{Enabled: &enabled},
+ map[string]bool{"enabled": true})
+}
+
+func TestUpdateDatasetDocumentAllowsFailEnabled(t *testing.T) {
+ enabled := 0
+ updateDatasetDocumentAllowed(t, string(entity.TaskStatusFail),
+ &UpdateDatasetDocumentRequest{Enabled: &enabled},
+ map[string]bool{"enabled": true})
+}
+
+func TestUpdateDatasetDocumentAllowsUnstartEnabled(t *testing.T) {
+ enabled := 0
+ updateDatasetDocumentAllowed(t, string(entity.TaskStatusUnstart),
+ &UpdateDatasetDocumentRequest{Enabled: &enabled},
+ map[string]bool{"enabled": true})
+}
+
+// TestUpdateDatasetDocumentRunningEmptyPresentNotRejected locks the
+// len(present) > 0 gate: an empty PATCH (no fields) on a RUNNING doc must not
+// be rejected by the run-state guard (it is a no-op, not an edit).
+func TestUpdateDatasetDocumentRunningEmptyPresentNotRejected(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertTestDocWithRun(t, "doc-1", "kb-1", string(entity.TaskStatusRunning), 0, 0)
+
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ _, code, err := svc.UpdateDatasetDocument(ctx, "tenant-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{}, map[string]bool{})
+ if err != nil {
+ t.Fatalf("empty PATCH on RUNNING doc should not be rejected: code=%v err=%v", code, err)
+ }
+ if code != common.CodeSuccess {
+ t.Fatalf("code = %v, want %v", code, common.CodeSuccess)
+ }
+}
+
+// TestUpdateDatasetDocumentRejectsRunningMetaFields pins that every editable
+// field is blocked while RUNNING, including meta_fields.
+func TestUpdateDatasetDocumentRejectsRunningMetaFields(t *testing.T) {
+ updateDatasetDocumentRejected(t, string(entity.TaskStatusRunning),
+ &UpdateDatasetDocumentRequest{MetaFields: map[string]any{"author": "x"}},
+ map[string]bool{"meta_fields": true})
+}
+
+// TestUpdateDatasetDocumentAllowsDoneRename proves an editable status is not
+// over-restricted: renaming a DONE document succeeds (no run-state error).
+func TestUpdateDatasetDocumentAllowsDoneRename(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "orig.txt", 0, 0)
+
+ name := "renamed.txt"
+ svc := testDocumentService(t)
+ ctx := t.Context()
+ _, code, err := svc.UpdateDatasetDocument(ctx, "tenant-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{Name: &name},
+ map[string]bool{"name": true})
+ if err != nil && strings.Contains(err.Error(), "cannot be modified") {
+ t.Fatalf("editable DONE doc was wrongly rejected: %v", err)
+ }
+ if err != nil {
+ t.Fatalf("unexpected non-run-state error: code=%v err=%v", code, err)
+ }
+}