{"record":{"id":"6b72f84765825861","repo":"neondatabase/neon","slug":"not-an-image-or-delta-layer-layer-file-path","errorCode":null,"errorMessage":"not an image or delta layer: {layer_file_path}","messagePattern":"not an image or delta layer: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pageserver/ctl/src/layers.rs","lineNumber":243,"sourceCode":"\n            let res = DeltaLayer::rewrite_summary(\n                layer_file_path,\n                rewrite_closure!(delta_layer::Summary),\n                &ctx,\n            )\n            .await;\n            match res {\n                Ok(()) => {\n                    println!(\"Successfully rewrote summary of delta layer {layer_file_path}\");\n                    return Ok(());\n                }\n                Err(delta_layer::RewriteSummaryError::MagicMismatch) => (), // fallthrough\n                Err(delta_layer::RewriteSummaryError::Other(e)) => {\n                    return Err(e);\n                }\n            }\n\n            anyhow::bail!(\"not an image or delta layer: {layer_file_path}\");\n        }\n    }\n}\n\nfn print_layer_file(idx: usize, layer_file: &LayerFile) {\n    println!(\n        \"[{:3}]  key:{}-{}\\n       lsn:{}-{}\\n       delta:{}\",\n        idx,\n        layer_file.key_range.start,\n        layer_file.key_range.end,\n        layer_file.lsn_range.start,\n        layer_file.lsn_range.end,\n        layer_file.is_delta,\n    );\n}\n","sourceCodeStart":225,"sourceCodeEnd":259,"githubUrl":"https://github.com/neondatabase/neon/blob/8f60b04da47ffefe0e52bda2440134b42874eb75/pageserver/ctl/src/layers.rs#L225-L259","documentation":"When rewriting a layer summary, the ctl first tries the file as an image layer and then as a delta layer; the delta path tolerates a magic mismatch and falls through. If neither path recognizes the file's magic bytes, the file is neither a recognized image nor delta layer, and the command bails. The file is corrupt, truncated, in an incompatible on-disk format, or simply not a layer file.","triggerScenarios":"Passing a path that is not a layer file (for example index_part.json or a pg control file), a truncated download, or a layer written by a pageserver with a different layer file version.","commonSituations":"Wrong file passed on the command line; interrupted downloads from remote storage; ctl and pageserver built from different versions with changed on-disk formats.","solutions":["Verify the file: check its size and first bytes; image and delta layers start with distinct magic values, and note that main.rs already tries pg control format before this path.","Re-download the layer from remote storage to rule out truncation or corruption.","Confirm the ctl build matches the pageserver version that wrote the layer."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// check the magic bytes before handing the file to layer tooling\nasync fn looks_like_layer_file(path: &Utf8Path) -> bool {\n    let mut magic = [0u8; 1];\n    tokio::fs::File::open(path).await.ok()\n        .and_then(|mut f| std::io::Read::read_exact(&mut f, &mut magic).ok())\n        .is_some()\n}","typeGuard":null,"tryCatchPattern":"// main.rs already tries pg control first; keep the same fallback shape in wrappers\nif let Err(e) = print_layerfile(&path).await {\n    if e.to_string().starts_with(\"not an image or delta layer\") {\n        // try the next candidate format or re-download the layer from remote storage\n        re_download_and_retry(&path).await?;\n    } else {\n        return Err(e);\n    }\n}","preventionTips":["Verify file identity and size before running layer tools; wrong files are the most common cause.","Re-download layers from remote storage when truncation is possible.","Keep the ctl version aligned with the pageserver that wrote the layer files."],"tags":["rust","neon","ctl","layer-file","file-format"],"backgroundTag":"unrecognized-file-format","analyzedSha":"8f60b04da47ffefe0e52bda2440134b42874eb75","analyzedAt":"2026-08-16T23:39:28.135Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}