clockworklabs/SpacetimeDB · info · io::Error

{} [{}]: {}

Error message

{} [{}]: {}

What it means

Not a distinct failure but the crate's error-context wrapper: any error raised while opening/resuming a segment is re-wrapped as '<segment path> [<context>]: <original error>' with the original ErrorKind preserved. The bracketed context names the failing step ('determining segment file size for resume', 'checking metadata', ...) and the leading path names the exact segment file involved.

Source

Thrown at crates/commitlog/src/repo/mod.rs:456

/// Obtain the canonical [CompressOnce] compressor for segments.
///
/// The compressor will create seekable [Zstd] archives with a max frame size
/// of 4KiB. That is, seeking to an arbitrary byte offset (of the uncompressed
/// segment) within the archive will decompress 4KiB of data on average.
pub fn segment_compressor() -> Zstd {
    Zstd {
        max_frame_size: Some(0x1000),
    }
}

fn segment_label<R: Repo>(repo: &R, offset: u64) -> String {
    repo.segment_file_path(offset)
        .unwrap_or_else(|| format!("offset {offset}"))
}

fn with_segment_context<R: Repo>(context: &'static str, repo: &R, offset: u64, source: io::Error) -> io::Error {
    io::Error::new(
        source.kind(),
        format!("{} [{}]: {}", segment_label(repo, offset), context, source),
    )
}

/// Allocate [Options::max_segment_size] of space for [FileLike]
/// if the `fallocate` feature is enabled,
/// and [Options::preallocate_segments] is `true`.
///
/// No-op otherwise.
#[inline]
pub(crate) fn fallocate(_f: &mut impl FileLike, _opts: &Options) -> io::Result<()> {
    #[cfg(feature = "fallocate")]
    if _opts.preallocate_segments {
        _f.fallocate(_opts.max_segment_size)?;
    }

    Ok(())

View on GitHub (pinned to 524b4487d9)

Solutions

1. Log the full chain: format with {:#} or walk err.source() to reach the root cause
2. Inspect the segment file named at the start of the message
3. Fix the inner error according to its own semantics (I/O, corruption, version mismatch)

fn has_segment_context(e: &io::Error) -> bool {
    // context wrapper shape: "<path> [<step>]: <inner>"
    e.to_string().contains("]: ")
}

// always log the full chain so the root cause survives the wrapper
if let Err(e) = open_result {
    let mut chain = e.to_string();
    let mut src: Option<&dyn std::error::Error> = e.source();
    while let Some(s) = src { chain.push_str(&format!(": {s}")); src = s.source(); }
    tracing::error!(error = %chain, "segment operation failed");
    return Err(e);
}

When it happens

Trigger: Any underlying failure during segment open/resume - I/O errors, decode failures, corruption - gets this wrapper; the text you must act on is the part after the final colon, which is the original error.

Common situations: Developers fixate on the wrapper phrase instead of the inner cause; with many segment files, the path prefix is what identifies which file to inspect.

Related errors

• InvalidInput
• AlreadyExists
• AlreadyExists
• NotFound
• InvalidData

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/468b88b0b3e75ae9. Report an issue: GitHub.