{"record":{"id":"1e1bf78808731d0d","repo":"weaviate/weaviate","slug":"failed-to-create-hfresh-merge-queue","errorCode":null,"errorMessage":"failed to create hfresh merge queue","messagePattern":"failed to create hfresh merge queue","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/repos/db/vector/hfresh/task_queue.go","lineNumber":150,"sourceCode":"\t\treturn nil, errors.Wrap(err, \"failed to initialize hfresh reassign queue\")\n\t}\n\n\ttq.analyzeQueue = &analyzeQueue{DiskQueue: aq, reassignQueue: tq.reassignQueue}\n\n\t// create queue for merge operations\n\ttq.mergeQueue, err = queue.NewDiskQueue(\n\t\tqueue.DiskQueueOptions{\n\t\t\tID:               fmt.Sprintf(\"hfresh_merge_queue_%s_%s\", index.config.ShardName, index.config.ID),\n\t\t\tLogger:           index.logger,\n\t\t\tScheduler:        index.scheduler,\n\t\t\tDir:              filepath.Join(index.config.RootPath, \"merge.queue.d\"),\n\t\t\tTaskDecoder:      &tq,\n\t\t\tOnBatchProcessed: tq.OnBatchProcessed,\n\t\t\tChunkSize:        mergeTaskQueueChunkSize,\n\t\t},\n\t)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"failed to create hfresh merge queue\")\n\t}\n\terr = tq.mergeQueue.Init()\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"failed to initialize hfresh merge queue\")\n\t}\n\n\treturn &tq, nil\n}\n\nfunc (tq *TaskQueue) Register() {\n\ttq.scheduler.RegisterQueue(tq.analyzeQueue)\n\ttq.scheduler.RegisterQueue(tq.splitQueue)\n\ttq.scheduler.RegisterQueue(tq.reassignQueue)\n\ttq.scheduler.RegisterQueue(tq.mergeQueue)\n}\n\nfunc (tq *TaskQueue) Close(ctx context.Context) error {\n\tvar errs []error","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/repos/db/vector/hfresh/task_queue.go#L132-L168","documentation":"NewTaskQueue creates the disk-backed merge queue under merge.queue.d for hfresh posting-merge operations. This wrapper fires when queue.NewDiskQueue fails (directory/I/O error), preventing merges from being scheduled and aborting index initialization.","triggerScenarios":"hfresh.New / NewTaskQueue where NewDiskQueue for the merge queue errors — unusable directory path, invalid DiskQueueOptions, or filesystem failure.","commonSituations":"Unwritable or missing RootPath, read-only filesystem, disk-full conditions, or custom/test code passing invalid DiskQueueOptions (empty ID, zero chunk size, nil decoder).","solutions":["Check permissions/disk space for the shard's merge.queue.d directory","Restart once storage is healthy"],"exampleFix":"// before\nDiskQueueOptions{ID: \"\", ChunkSize: 0} // invalid in custom harness\n// after\nDiskQueueOptions{ID: \"hfresh_merge_queue_<shard>_<id>\", ChunkSize: mergeTaskQueueChunkSize, Logger: logger, Dir: filepath.Join(root, \"merge.queue.d\")}","handlingStrategy":"validation","validationCode":"mergeDir := filepath.Join(rootPath, \"merge.queue.d\")\nif err := os.MkdirAll(mergeDir, 0o755); err != nil {\n    return fmt.Errorf(\"cannot prepare merge queue dir %s: %v\", mergeDir, err)\n}\n// validate options if constructing manually\nif opts.ID == \"\" || opts.ChunkSize <= 0 || opts.TaskDecoder == nil { return errors.New(\"invalid DiskQueueOptions\") }","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"failed to create hfresh merge queue\") {\n    return fmt.Errorf(\"merge queue creation failed at %s: %w\", filepath.Join(rootPath, \"merge.queue.d\"), err)\n}","preventionTips":["Preflight writable-volume checks in startup scripts.","Never point RootPath at read-only or ephemeral filesystems.","Set ENOSPC alerts on the data volume.","Validate all DiskQueueOptions fields when constructing queues in tests."],"tags":["disk-queue","startup","filesystem","hfresh"],"backgroundTag":"disk-queue-create-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"}