{"record":{"id":"ab2726226319be4d","repo":"can1357/oh-my-pi","slug":"invalid-tar-numeric-value","errorCode":null,"errorMessage":"Invalid tar numeric value","messagePattern":"Invalid tar numeric value","errorType":"exception","errorClass":"ArchiveError","httpStatus":null,"severity":"error","filePath":"packages/utils/src/ar/tar.ts","lineNumber":611,"sourceCode":"export function sniffTar(bytes: Uint8Array): boolean {\n\tif (bytes.byteLength < BLOCK_SIZE) return false;\n\tif (isZeroBlock(bytes, 0)) return true;\n\ttry {\n\t\tif (readTarString(bytes, NAME_OFFSET, NAME_LENGTH).length === 0) return false;\n\t\tconst size = readTarSize(bytes, SIZE_OFFSET);\n\t\treturn Number.isSafeInteger(paddedSize(size)) && checksumMatches(bytes, 0);\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction writeField(target: Uint8Array, offset: number, length: number, value: Uint8Array): void {\n\tif (value.byteLength > length) throw new ArchiveError(\"Tar header field is too long\");\n\ttarget.set(value, offset);\n}\n\nfunction writeOctal(target: Uint8Array, offset: number, length: number, value: number): void {\n\tif (!Number.isSafeInteger(value) || value < 0) throw new ArchiveError(\"Invalid tar numeric value\");\n\tconst digits = value.toString(8);\n\tif (digits.length > length - 1) throw new ArchiveError(\"Tar numeric value does not fit its header field\");\n\tfor (let index = offset; index < offset + length - 1 - digits.length; index++) target[index] = 0x30;\n\tfor (let index = 0; index < digits.length; index++)\n\t\ttarget[offset + length - 1 - digits.length + index] = digits.charCodeAt(index);\n\ttarget[offset + length - 1] = 0;\n}\n\nfunction splitUstarPath(pathBytes: Uint8Array): readonly [Uint8Array, Uint8Array] | undefined {\n\tif (pathBytes.byteLength <= NAME_LENGTH) return [pathBytes, new Uint8Array(0)];\n\tfor (let index = pathBytes.byteLength - 1; index > 0; index--) {\n\t\tif (pathBytes[index] !== 0x2f) continue;\n\t\tconst prefix = pathBytes.subarray(0, index);\n\t\tconst name = pathBytes.subarray(index + 1);\n\t\tif (prefix.byteLength <= PREFIX_LENGTH && name.byteLength > 0 && name.byteLength <= NAME_LENGTH) {\n\t\t\treturn [name, prefix];\n\t\t}\n\t}","sourceCodeStart":593,"sourceCodeEnd":629,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/utils/src/ar/tar.ts#L593-L629","documentation":"Tar stores numeric fields (mode, uid, size, mtime) as zero-padded octal ASCII. writeOctal validates the value before encoding: it must be a safe non-negative integer. Negative numbers, NaN, non-integers, or values beyond Number.MAX_SAFE_INTEGER cannot be represented and would corrupt the header, so this ArchiveError is thrown.","triggerScenarios":"Writing a tar entry whose size came from a computation yielding NaN, a negative mtime (pre-1970 timestamps), a uid/gid read as -1 (unknown owner convention), or a size value that is not a Number safe integer (e.g. parsed from a string or BigInt).","commonSituations":"System calls returning -1 for unavailable uid/gid being passed through verbatim; dates before the Unix epoch (old photo metadata, zip imports); sizes from JSON string fields not converted with Number; float sizes from unit conversions.","solutions":["Sanitize numeric fields before writing: `Number.isSafeInteger(v) && v >= 0` or clamp (e.g. uid=-1 → 0)","Convert string sizes explicitly with Number() and validate before use","For pre-epoch timestamps, clamp mtime to 0 or use PAX base-256/extended records if supported","If you need values above 2^53, use the base-256 GNU encoding path instead of the octal writer"],"exampleFix":"// before: uid of -1 (unknown) corrupts the header\nawait writeTar({ path, uid: stat.uid });\n// after: clamp unsafe values\nawait writeTar({ path, uid: Number.isSafeInteger(stat.uid) && stat.uid >= 0 ? stat.uid : 0 });","handlingStrategy":"validation","validationCode":"function assertTarNumber(v: number, field: string): void {\n  if (!Number.isSafeInteger(v) || v < 0) {\n    throw new Error(`${field} must be a non-negative safe integer, got ${v}`);\n  }\n}","typeGuard":"function isValidTarNumber(v: unknown): v is number {\n  return typeof v === \"number\" && Number.isSafeInteger(v) && v >= 0;\n}","tryCatchPattern":null,"preventionTips":["Clamp uid/gid/mode defaults: unknown owner (-1) becomes 0","Coerce sizes from strings with Number() and validate before writing","Clamp mtimes to >= 0 (epoch) for pre-1970 metadata"],"tags":["tar","writer","numeric","octal","validation"],"backgroundTag":"tar-invalid-numeric-field","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}