{"record":{"id":"ba02ec7762ea9b32","repo":"kopia/kopia","slug":"unable-to-write-header-ba02ec","errorCode":null,"errorMessage":"unable to write header","messagePattern":"unable to write header","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/content/index/index_v2.go","lineNumber":525,"sourceCode":"\t}\n\n\tuniqueFormatInfo2IndexLen := len(b2.uniqueFormatInfo2Index)\n\tif uniqueFormatInfo2IndexLen > maxUInt8 {\n\t\treturn errors.Errorf(\"invalid unique format v2 info index length: %v\", uniqueFormatInfo2IndexLen)\n\t}\n\n\t// write header\n\theader := make([]byte, v2IndexHeaderSize)\n\theader[0] = Version2                                                   // version\n\theader[1] = byte(b2.keyLength)                                         //nolint:gosec // range checked above\n\tbinary.BigEndian.PutUint16(header[2:4], uint16(b2.entrySize))          //nolint:gosec\n\tbinary.BigEndian.PutUint32(header[4:8], uint32(b2.entryCount))         //nolint:gosec\n\tbinary.BigEndian.PutUint32(header[8:12], uint32(len(b2.packID2Index))) //nolint:gosec\n\theader[12] = byte(uniqueFormatInfo2IndexLen)\n\tbinary.BigEndian.PutUint32(header[13:17], uint32(b2.baseTimestamp)) //nolint:gosec\n\n\tif _, err := w.Write(header); err != nil {\n\t\treturn errors.Wrap(err, \"unable to write header\")\n\t}\n\n\t// write sorted index entries\n\tfor _, it := range sortedInfos {\n\t\tif err := b2.writeIndexEntry(w, it); err != nil {\n\t\t\treturn errors.Wrap(err, \"unable to write entry\")\n\t\t}\n\t}\n\n\t// write pack ID entries in the index order of values from packID2Index (0, 1, 2, ...).\n\treversePackIDIndex := make([]blob.ID, len(b2.packID2Index))\n\tfor k, v := range b2.packID2Index {\n\t\treversePackIDIndex[v] = k\n\t}\n\n\t// emit pack ID information in this order.\n\tfor _, e := range reversePackIDIndex {\n\t\tif err := b2.writePackIDEntry(w, e); err != nil {","sourceCodeStart":507,"sourceCodeEnd":543,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/repo/content/index/index_v2.go#L507-L543","documentation":"This error wraps a failed Write of the v2 index header (a 17+ byte binary header) to the underlying writer w during index Finish. The header includes version, key length, entry count, pack ID count, format-info count and base timestamp; if writing those bytes fails, the error is wrapped with \"unable to write header\" so the failure point is identifiable. The root cause is whatever the underlying writer reported.","triggerScenarios":"Any io.Writer error returned by w.Write(header) in the v2 index Finish path — disk full, closed writer, broken pipe to a pipe/network sink, or permission issues on the output file.","commonSituations":"Running out of disk space while committing an index, writing to an already-closed buffer, or streaming the index to a destination that disappeared mid-write.","solutions":["Inspect the wrapped cause with %+v to see the underlying write error (ENOSPC, EPIPE, file closed, etc.).","Check available disk space and quotas on the destination volume; free space or redirect the index output.","Ensure the writer is valid and open for the whole duration of the Finish call.","Retry the index build after fixing the storage condition; the index was not fully written."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// check writable space before building:\nif stat, err := outDirStat(); err != nil || stat.freeBytes() < estimatedIndexSize {\n    return errors.New(\"insufficient space for index output\")\n}","typeGuard":null,"tryCatchPattern":"if err := idxBuilder.Finish(w); err != nil && strings.Contains(err.Error(), \"unable to write header\") {\n    log.Errorf(\"index header write failed: %+v\", err) // inspect wrapped cause\n}","preventionTips":["Monitor free disk space on the index output volume.","Keep the writer open for the whole Finish duration.","Write to a local temp file, then move into place atomically.","Unwrap and log the cause (%+v), not just the wrapper message."],"tags":["go","io","file-write","header"],"backgroundTag":"file-write-failed","analyzedSha":"82495e54b584c1ef6073c9e1be048f57f8aef078","analyzedAt":"2026-09-07T20:35:21.689Z","contentChangedAt":"2026-09-07T20:35:21.689Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}