diff --git a/block/src/error.rs b/block/src/error.rs
new file mode 100644
index 000000000..a8dc2c1ad
--- /dev/null
+++ b/block/src/error.rs
@@ -0,0 +1,17 @@
+// Copyright 2025 The Cloud Hypervisor Authors. All rights reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+//! Unified error handling for the block crate.
+//!
+//! # Architecture
+//!
+//! ```text
+//! BlockError                 -- single public error type
+//!  |-- BlockErrorKind        -- small, stable, matchable classification
+//!  |-- ErrorContext          -- optional diagnostic metadata (path, offset, op)
+//!  +-- source                -- format-specific error (boxed)
+//!         |-- QcowError
+//!         |-- VhdError / RawError / ...
+//!         +-- io::Error / etc.
+//! ```
diff --git a/block/src/lib.rs b/block/src/lib.rs
index f8d56cf10..1b739beaf 100644
--- a/block/src/lib.rs
+++ b/block/src/lib.rs
@@ -9,6 +9,7 @@
 // SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause
 
 pub mod async_io;
+pub mod error;
 pub mod fcntl;
 pub mod fixed_vhd;
 #[cfg(feature = "io_uring")]