{"record":{"id":"30f1f26b65e496ba","repo":"influxdata/influxdb","slug":"invalid-header-reason","errorCode":null,"errorMessage":"invalid header: {reason}","messagePattern":"invalid header: (.+?)","errorType":"error_code","errorClass":"FormatError","httpStatus":null,"severity":"critical","filePath":"influxdb3_catalog/src/format/mod.rs","lineNumber":210,"sourceCode":"    UnknownNonUpgradeSafeRecord { record_id: u16 },\n\n    /// Invalid record length.\n    #[error(\"invalid record length: {length}\")]\n    InvalidRecordLength { length: u32 },\n\n    /// Record data exceeds remaining file.\n    #[error(\n        \"record data exceeds file bounds: offset {offset}, length {length}, file size {file_size}\"\n    )]\n    RecordExceedsFile {\n        offset: u64,\n        length: u32,\n        file_size: u64,\n    },\n\n    /// File header is internally inconsistent (e.g. a reserved field is\n    /// nonzero).\n    #[error(\"invalid header: {reason}\")]\n    InvalidHeader { reason: &'static str },\n\n    /// A `RestoreCatalog` record was encountered during sync apply with an\n    /// empty preload. Callers on a persistence path must first load the\n    /// backup state off-lock via `preload_restore_for_records` /\n    /// `preload_restore_for_file` and pass the resulting `RestorePreload`\n    /// into the apply call.\n    #[error(\n        \"RestoreCatalog record encountered without object-store access \\\n         (sync apply path): the catalog cannot reload backup state from \\\n         here — use the async apply path\"\n    )]\n    RestoreRequiresStore,\n\n    /// Loading the backup snapshot/log files referenced by a `RestoreCatalog`\n    /// record failed.\n    #[error(\"failed to load restore source: {0}\")]\n    RestoreLoadFailed(String),","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/format/mod.rs#L192-L228","documentation":"The catalog file header is internally inconsistent — for example a field documented as reserved is nonzero. The reader validates the header layout before trusting any records; a violation means the file was not produced by a compatible writer or its bytes were altered.","triggerScenarios":"Opening a file that is not a valid catalog snapshot/log but was pointed at the catalog path; a header corrupted in its reserved/constant fields; a file written by incompatible or hand-crafted tooling.","commonSituations":"Misconfiguring the catalog directory to point at the wrong path (e.g. a data file or an unrelated format); restoring files from a different InfluxDB edition/format; corrupted disk blocks in the header page.","solutions":["Point the instance at the correct catalog directory (check config for the data/plugin paths).","Restore the catalog files from a backup produced by the same InfluxDB 3 version/format.","Do not modify or generate catalog files with custom scripts; use the supported restore commands."],"exampleFix":"// before: influxdb3 serve --node-id=... --object-store=file --data-dir=/path/to/random/dir\n// after: point at the real data dir containing the catalog\n// influxdb3 serve --object-store=file --data-dir=/var/lib/influxdb3","handlingStrategy":"validation","validationCode":"// Confirm the data dir actually contains an InfluxDB 3 catalog before serving\nif !data_dir.join(\"catalog\").exists() {\n    return Err(format!(\"{} does not look like an influxdb3 data dir\", data_dir.display()));\n}","typeGuard":null,"tryCatchPattern":"if let Err(e) = catalog.open() {\n    if e.to_string().contains(\"invalid header\") {\n        eprintln!(\"check --data-dir/--object-store config and file provenance\");\n    }\n}","preventionTips":["Double-check data-dir and object-store config paths at deploy time","Restore only backups produced by the same edition/format","Never generate or modify catalog files with custom scripts"],"tags":["header","format","catalog","corruption"],"backgroundTag":"schema-validation-failed","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}