{"record":{"id":"2de1b1018b055e8e","repo":"thanos-io/thanos","slug":"add-index-meta","errorCode":null,"errorMessage":"add index meta","messagePattern":"add index meta","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/block/indexheader/binary_reader.go","lineNumber":134,"sourceCode":"\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"new index reader\")\n\t}\n\ttmpFilename := \"\"\n\tif filename != \"\" {\n\t\ttmpFilename = filename + \".tmp\"\n\t}\n\n\t// Buffer for copying and encbuffers.\n\t// This also will control the size of file writer buffer.\n\tbuf := make([]byte, 32*1024)\n\tbw, err := newBinaryWriter(id, tmpFilename, buf)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"new binary index header writer\")\n\t}\n\tdefer runutil.CloseWithErrCapture(&err, bw, \"close binary writer for %s\", tmpFilename)\n\n\tif err := bw.AddIndexMeta(indexVersion, ir.toc.PostingsTable); err != nil {\n\t\treturn nil, errors.Wrap(err, \"add index meta\")\n\t}\n\n\tif err := ir.CopySymbols(bw.SymbolsWriter(), buf); err != nil {\n\t\treturn nil, err\n\t}\n\n\tif err := bw.writer.Flush(); err != nil {\n\t\treturn nil, errors.Wrap(err, \"flush\")\n\t}\n\n\tif err := ir.CopyPostingsOffsets(bw.PostingOffsetsWriter(), buf); err != nil {\n\t\treturn nil, err\n\t}\n\n\tif err := bw.writer.Flush(); err != nil {\n\t\treturn nil, errors.Wrap(err, \"flush\")\n\t}\n","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/pkg/block/indexheader/binary_reader.go#L116-L152","documentation":"WriteBinary serializes an index-header file for a TSDB block. The first serialization step is bw.AddIndexMeta(indexVersion, ir.toc.PostingsTable), which writes the index version and postings-table offset into the buffered writer. This error wraps any failure returned by that call, most commonly an underlying write/flush error from the bufio.Writer backing the binary writer (e.g. disk full, I/O error) or an unsupported index version.","triggerScenarios":"Calling WriteBinary (directly or via NewBinaryReader / NewLazyBinaryReader) on a block whose on-disk or in-memory index write fails during the very first write to the bufio.Writer: AddIndexMeta writes the magic/version/postings-offset and the buffered writer's first flush to the underlying file or buffer fails (disk full, EIO, permission issue on the temp file).","commonSituations":"Store Gateway or Compactor rebuilding an index-header on a disk that is full or failing; writing into a directory without write permission (the .tmp temp file); a corrupted or unsupported index version being passed through.","solutions":["Check free disk space on the volume holding the block directory (df -h) and clean up if full.","Verify write permissions on the directory containing the index-header temp file (<filename>.tmp).","Check dmesg / filesystem health for underlying I/O errors on the disk.","Re-download or re-upload the block's index file if the source index is corrupted (invalid version/TOC).","Retry WriteBinary; transient I/O failures on network-backed storage can clear on retry."],"exampleFix":"// before: no preflight space/permission check, error surfaces only here\nbw, err := newBinaryWriter(id, tmpFilename, buf)\n...\n// after: fail early with a clear message\nif err := checkWritable(tmpFilename); err != nil {\n    return nil, errors.Wrapf(err, \"index-header dir %s not writable\", filepath.Dir(tmpFilename))\n}","handlingStrategy":"validation","validationCode":"// Go: preflight writable temp dir with enough space before WriteBinary\nfunc canWriteIndexHeader(dir string) error {\n    info, err := os.Stat(dir)\n    if err != nil { return err }\n    if !info.IsDir() { return fmt.Errorf(\"%s is not a directory\", dir) }\n    probe := filepath.Join(dir, \".write-probe\")\n    if err := os.WriteFile(probe, []byte(\"x\"), 0o644); err != nil { return err }\n    return os.Remove(probe)\n}","typeGuard":null,"tryCatchPattern":"// Go\nir, err := indexheader.WriteBinary(ctx, bkt, id, dst)\nif err != nil {\n    if strings.Contains(err.Error(), \"add index meta\") {\n        // disk/permission problem writing the index-header temp file\n        log.Error(\"index-header build failed at AddIndexMeta; check disk space/permissions\", \"err\", err)\n    }\n    return err\n}","preventionTips":["Monitor disk usage on store-gateway/compactor data volumes and alert before 90% full.","Run Thanos containers with a dedicated writable volume and correct fsGroup/runAsUser.","Delete stale .tmp index-header files during restart cleanup.","Watch kernel logs for early signs of storage device failure."],"tags":["io","filesystem","thanos","index-header"],"backgroundTag":"file-write-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"}