{"record":{"id":"b8b6e833b643d01e","repo":"tursodatabase/turso","slug":"punch-hole-is-not-supported-for-the-given-io-imple","errorCode":null,"errorMessage":"punch_hole is not supported for the given IO implementation","messagePattern":"punch_hole is not supported for the given IO implementation","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/io/mod.rs","lineNumber":215,"sourceCode":"        Ok(c)\n    }\n    fn size(&self) -> Result<u64>;\n    fn truncate(&self, len: u64, c: Completion) -> Result<Completion>;\n\n    /// Optional method implemented by the IO which supports \"partial\" files (e.g. file with \"holes\")\n    /// This method is used in sync engine only for now (in partial sync mode) and never used in the core database code\n    ///\n    /// The hole is the contiguous file region which is not allocated by the file-system\n    /// If there is a single byte which is allocated within a given range - method must return false in this case\n    // todo: need to add custom completion type?\n    fn has_hole(&self, _pos: usize, _len: usize) -> Result<bool> {\n        panic!(\"has_hole is not supported for the given IO implementation\")\n    }\n    /// Optional method implemented by the IO which supports \"partial\" files (e.g. file with \"holes\")\n    /// This method is used in sync engine only for now (in partial sync mode) and never used in the core database code\n    // todo: need to add custom completion type?\n    fn punch_hole(&self, _pos: usize, _len: usize) -> Result<()> {\n        panic!(\"punch_hole is not supported for the given IO implementation\")\n    }\n\n    fn shared_wal_lock_byte(\n        &self,\n        _offset: u64,\n        _exclusive: bool,\n        _kind: SharedWalLockKind,\n    ) -> Result<()> {\n        Err(crate::LimboError::InternalError(\n            \"shared WAL coordination byte locking is not supported for this file\".into(),\n        ))\n    }\n\n    fn shared_wal_try_lock_byte(\n        &self,\n        _offset: u64,\n        _exclusive: bool,\n        _kind: SharedWalLockKind,","sourceCodeStart":197,"sourceCodeEnd":233,"githubUrl":"https://github.com/tursodatabase/turso/blob/6c7252267988c76e632af00a671e4b9788dfae13/core/io/mod.rs#L197-L233","documentation":"punch_hole() is an optional IO trait method whose default implementation panics. It de-allocates contiguous file regions (holes) and is used by the sync engine in partial-sync mode only; core database code never calls it. Invoking it on an IO backend that did not override it crashes.","triggerScenarios":"Partial sync running punch_hole on an IO without sparse-file support: in-memory IO, custom test backends, or filesystems where hole punching is unavailable (NFS varies, older tmpfs, some Windows configs).","commonSituations":"Testing the sync engine against memory IO; deploying partial sync onto a filesystem without fallocate/FALLOC_FL_PUNCH_HOLE.","solutions":["Run partial sync on the file-backed platform IO over a filesystem supporting hole punching (ext4, XFS, btrfs)","Disable partial-sync mode and use full sync","For custom IO: implement punch_hole()/has_hole() or maintain an allocation map"],"exampleFix":"// before\n// partial sync punches holes through an IO that cannot -> panics\nengine.enable_partial_sync(memory_io);\n\n// after\n// file-backed IO on ext4/xfs implements punch_hole via fallocate\nengine.enable_partial_sync(platform_file_io);","handlingStrategy":"fallback","validationCode":"// same capability gate as has_hole: only punch holes through file-backed IO\nif !io_supports_holes(&io) {\n    engine.use_full_sync(); // avoid punch_hole entirely\n} else {\n    engine.enable_partial_sync(io);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Verify the target filesystem supports fallocate hole punching before enabling partial sync","Never run partial sync against memory or custom test IO backends"],"tags":["io","sync","sparse-files","trait-default-panic","panic"],"backgroundTag":"unsupported-io-operation","analyzedSha":"6c7252267988c76e632af00a671e4b9788dfae13","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}