weaviate/weaviate · error

pause queue: %w

Error message

pause queue: %w

What it means

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).

Source

Thrown at adapters/repos/db/vector/hfresh/hfresh.go:356

	return stderrors.Join(errs...)
}

func (h *HFresh) PrepareForBackup(ctx context.Context) error {
	err := h.Centroids.hnsw.PrepareForBackup(ctx)
	if err != nil {
		return err
	}

	for _, queue := range []*queue.DiskQueue{
		h.taskQueue.analyzeQueue.DiskQueue,
		h.taskQueue.splitQueue,
		h.taskQueue.reassignQueue,
		h.taskQueue.mergeQueue,
	} {
		err := queue.PrepareForBackup(ctx)
		if err != nil {
			return fmt.Errorf("pause queue: %w", err)
		}
	}

	return nil
}

func (h *HFresh) ResumeAfterBackup(ctx context.Context) error {
	for _, queue := range []*queue.DiskQueue{
		h.taskQueue.analyzeQueue.DiskQueue,
		h.taskQueue.splitQueue,
		h.taskQueue.reassignQueue,
		h.taskQueue.mergeQueue,
	} {
		queue.DisableMaintenanceMode()
	}

	return h.Centroids.hnsw.ResumeAfterBackup(ctx)
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Inspect the wrapped root cause (%w) in the error chain with errors.Unwrap/errors.As and fix that condition first
2. Retry the backup with a fresh, longer-lived context once queues are idle
3. Ensure no concurrent backups run against the same index and that prior PrepareForBackup calls completed/cleaned up (resume queues after a failed attempt)

Example fix

// before
err := idx.PrepareForBackup(ctx) // ctx with 1s timeout fails under load
// after
ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
defer cancel()
err := idx.PrepareForBackup(ctx)
if err != nil {
    log.Errorf("backup prep failed: %v", err) // log full chain to see root cause
}

if ctx.Err() != nil {
    return fmt.Errorf("cannot prepare backup: context already done: %w", ctx.Err())
}

err := idx.PrepareForBackup(ctx)
if err != nil {
    var root error = err
    for errors.Unwrap(root) != nil { root = errors.Unwrap(root) }
    log.Errorf("backup prep failed: %v (root: %v)", err, root)
    // resume queues / retry with fresh, longer context
}

When it happens

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

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

Related errors

• index is not hnsw
• posting not found
• tombstone cleanup already running
• class changed concurrently
• replica movement in progress

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/46a97708d0789233. Report an issue: GitHub.