{"record":{"id":"4d25eb9c9077fbbb","repo":"thanos-io/thanos","slug":"read-index-header","errorCode":null,"errorMessage":"read index header","messagePattern":"read index header","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/block/indexheader/lazy_binary_reader.go","lineNumber":113,"sourceCode":"// (mmap) the index-header; it will be loaded at first Reader function call.\nfunc NewLazyBinaryReader(\n\tctx context.Context,\n\tlogger log.Logger,\n\tbkt objstore.BucketReader,\n\tdir string,\n\tid ulid.ULID,\n\tpostingOffsetsInMemSampling int,\n\tmetrics *LazyBinaryReaderMetrics,\n\tbinaryReaderMetrics *BinaryReaderMetrics,\n\tonClosed func(*LazyBinaryReader),\n\tlazyDownload bool,\n) (*LazyBinaryReader, error) {\n\tif dir != \"\" && !lazyDownload {\n\t\tindexHeaderFile := filepath.Join(dir, id.String(), block.IndexHeaderFilename)\n\t\t// If the index-header doesn't exist we should download it.\n\t\tif _, err := os.Stat(indexHeaderFile); err != nil {\n\t\t\tif !os.IsNotExist(err) {\n\t\t\t\treturn nil, errors.Wrap(err, \"read index header\")\n\t\t\t}\n\n\t\t\tlevel.Debug(logger).Log(\"msg\", \"the index-header doesn't exist on disk; recreating\", \"path\", indexHeaderFile)\n\n\t\t\tstart := time.Now()\n\t\t\tif _, err := WriteBinary(ctx, bkt, id, indexHeaderFile, binaryReaderMetrics.downloadDuration); err != nil {\n\t\t\t\treturn nil, errors.Wrap(err, \"write index header\")\n\t\t\t}\n\n\t\t\tlevel.Debug(logger).Log(\"msg\", \"built index-header file\", \"path\", indexHeaderFile, \"elapsed\", time.Since(start))\n\t\t}\n\t}\n\n\treturn &LazyBinaryReader{\n\t\tctx:                         ctx,\n\t\tlogger:                      logger,\n\t\tbkt:                         bkt,\n\t\tdir:                         dir,","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/pkg/block/indexheader/lazy_binary_reader.go#L95-L131","documentation":"NewLazyBinaryReader wraps os.Stat errors (other than not-exist) when checking for the index-header file with 'read index header'. The file's existence cannot even be determined — a filesystem/permission problem, not a missing file.","triggerScenarios":"NewLazyBinaryReader(dir, id, ..., lazyDownload=false) where os.Stat on <dir>/<block-id>/index-header fails with permission or I/O errors (not IsNotExist).","commonSituations":"Wrong data directory configured; read-only or damaged local disk; permission changes on the cache directory; container volume mount issues.","solutions":["Fix permissions on the block cache directory (chmod/chown so the Thanos process can stat files)","Verify the configured --store.index-cache / data directory path is correct and mounted","Check disk health and mount status in the container/host","If the directory is wrong, correct the configuration and restart"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if _, err := os.Stat(filepath.Join(dir, id.String(), block.IndexHeaderFilename)); err != nil && !os.IsNotExist(err) { /* fix fs permissions/mount before constructing reader */ }","typeGuard":null,"tryCatchPattern":"r, err := indexheader.NewLazyBinaryReader(...); if err != nil && strings.Contains(err.Error(), \"read index header\") { check dir permissions; fail fast with actionable message }","preventionTips":["Run the process with read access to the data directory","Verify volume mounts in containers start correctly","Alert on EACCES/EBUSY from the cache directory"],"tags":["filesystem","permission","index-header","os-stat"],"backgroundTag":"file-read-failed","analyzedSha":"35b8b991177def87ed52dcf10f9b6d87f07282c8","analyzedAt":"2026-09-07T01:49:59.689Z","contentChangedAt":"2026-09-07T01:49:59.689Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}