{"record":{"id":"46a97708d0789233","repo":"weaviate/weaviate","slug":"pause-queue-w","errorCode":null,"errorMessage":"pause queue: %w","messagePattern":"pause queue: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/repos/db/vector/hfresh/hfresh.go","lineNumber":356,"sourceCode":"\n\treturn stderrors.Join(errs...)\n}\n\nfunc (h *HFresh) PrepareForBackup(ctx context.Context) error {\n\terr := h.Centroids.hnsw.PrepareForBackup(ctx)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tfor _, queue := range []*queue.DiskQueue{\n\t\th.taskQueue.analyzeQueue.DiskQueue,\n\t\th.taskQueue.splitQueue,\n\t\th.taskQueue.reassignQueue,\n\t\th.taskQueue.mergeQueue,\n\t} {\n\t\terr := queue.PrepareForBackup(ctx)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"pause queue: %w\", err)\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc (h *HFresh) ResumeAfterBackup(ctx context.Context) error {\n\tfor _, queue := range []*queue.DiskQueue{\n\t\th.taskQueue.analyzeQueue.DiskQueue,\n\t\th.taskQueue.splitQueue,\n\t\th.taskQueue.reassignQueue,\n\t\th.taskQueue.mergeQueue,\n\t} {\n\t\tqueue.DisableMaintenanceMode()\n\t}\n\n\treturn h.Centroids.hnsw.ResumeAfterBackup(ctx)\n}","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/repos/db/vector/hfresh/hfresh.go#L338-L374","documentation":"PrepareForBackup iterates the HNSW-fresh task queues (split, reassign, merge) pausing each one before a backup snapshot. If any queue fails to pause, the underlying error is wrapped with 'pause queue: %w' and propagated, aborting backup preparation. It is a wrapper that preserves the root cause (e.g. a context cancellation or queue shutdown failure).","triggerScenarios":"Calling PrepareForBackup (via the backup coordinator's anonymous callback) when one of the hfresh queues cannot be paused — e.g. ctx already cancelled/expired, a queue worker in a bad state, or concurrent backup attempts.","commonSituations":"Backups timing out because the context deadline is too short; backups racing with heavy ingest that keeps queues busy; repeated/concurrent backup requests hitting the same shard index.","solutions":["Inspect the wrapped root cause (%w) in the error chain with errors.Unwrap/errors.As and fix that condition first","Retry the backup with a fresh, longer-lived context once queues are idle","Ensure no concurrent backups run against the same index and that prior PrepareForBackup calls completed/cleaned up (resume queues after a failed attempt)"],"exampleFix":"// before\nerr := idx.PrepareForBackup(ctx) // ctx with 1s timeout fails under load\n// after\nctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)\ndefer cancel()\nerr := idx.PrepareForBackup(ctx)\nif err != nil {\n    log.Errorf(\"backup prep failed: %v\", err) // log full chain to see root cause\n}","handlingStrategy":"retry","validationCode":"if ctx.Err() != nil {\n    return fmt.Errorf(\"cannot prepare backup: context already done: %w\", ctx.Err())\n}","typeGuard":null,"tryCatchPattern":"err := idx.PrepareForBackup(ctx)\nif err != nil {\n    var root error = err\n    for errors.Unwrap(root) != nil { root = errors.Unwrap(root) }\n    log.Errorf(\"backup prep failed: %v (root: %v)\", err, root)\n    // resume queues / retry with fresh, longer context\n}","preventionTips":["Use generous timeouts for backup contexts on busy shards","Avoid concurrent backups against the same index","Always resume queues after a failed PrepareForBackup","Log the full error chain to identify the failing queue"],"tags":["go","backup","hnsw","concurrency"],"backgroundTag":"backup-preparation-failed","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}