Hmbown/CodeWhale · warning · std::io::Error

workspace too large for snapshots (over {} GB of non-exclude

Error message

workspace too large for snapshots (over {} GB of non-excluded content or > {} entries): {}
  raise `[snapshots] max_workspace_gb` in config.toml (or set it to 0 to disable the cap) if you want snapshots on this workspace.

What it means

A first-init size guard in open_or_init_with_cap: before creating a fresh snapshot repo, estimate_workspace_size_bounded walks the workspace and returns None if non-excluded content exceeds cap_bytes (from [snapshots] max_workspace_gb) or the entry count exceeds SIZE_WALK_MAX_ENTRIES. The error is InvalidInput and its message already names the two remedies. The walk only runs on first init — a workspace that fit initially may grow and is instead handled by aggressive pruning in snapshot().

Source

Thrown at crates/tui/src/snapshot/repo.rs:260

                    work_tree.display()
                ),
            ));
        }

        let _ = ensure_snapshot_dir(&work_tree)?;
        let git_dir = snapshot_git_dir(&work_tree);

        let needs_init = !git_dir.exists();
        if needs_init {
            // First-init size guard. Skipping this on subsequent opens
            // is intentional: paying a workspace walk on every snapshot
            // would defeat the purpose of the cap, and a workspace
            // that fit on first init is allowed to grow within the
            // existing repo's `MAX_SNAPSHOT_SIZE_MB` budget. Users on
            // workspaces that grew past the cap mid-session get the
            // existing aggressive-pruning path in `snapshot()`.
            if estimate_workspace_size_bounded(&work_tree, cap_bytes).is_none() {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidInput,
                    format!(
                        "workspace too large for snapshots (over {} GB of non-excluded content or > {} entries): {}\n  raise `[snapshots] max_workspace_gb` in config.toml (or set it to 0 to disable the cap) if you want snapshots on this workspace.",
                        cap_bytes / (1024 * 1024 * 1024),
                        SIZE_WALK_MAX_ENTRIES,
                        work_tree.display()
                    ),
                ));
            }
            let parent = git_dir.parent().ok_or_else(|| {
                io::Error::new(io::ErrorKind::InvalidInput, "snapshot dir has no parent")
            })?;
            std::fs::create_dir_all(parent)?;
            // `git init` here uses the parent directory as the work tree
            // and stores metadata in `.git`. We then continue to use
            // explicit `--git-dir` / `--work-tree` flags for every other
            // command so behaviour is invariant of cwd.
            let init = crate::dependencies::Git::command()

View on GitHub (pinned to 0c42157ee5)

Solutions

  1. Raise [snapshots] max_workspace_gb in config.toml to cover the real workspace size
  2. Set [snapshots] max_workspace_gb = 0 in config.toml to disable the cap entirely if you accept the cost
  3. Shrink non-excluded content: add snapshot excludes for vendor/build/data directories or move bulk data out of the workspace
  4. Re-run after shrinking — the guard only fires when the snapshot repo needs first initialization

Example fix

# before
# config.toml
[snapshots]
max_workspace_gb = 1   # Err: workspace too large for snapshots ...

# after
[snapshots]
max_workspace_gb = 8   # or 0 to disable the cap
Defensive patterns

Strategy: validation

Validate before calling

// Before first-time snapshot enable, size-check the workspace the same way the guard does.
use walkdir::WalkDir;
let entries = WalkDir::new(&ws).into_iter().filter_map(Result::ok).count();
let total: u64 = WalkDir::new(&ws).into_iter().filter_map(Result::ok)
    .filter_map(|e| e.metadata().ok().map(|m| m.len())).sum();
if total > cap_bytes || entries > entry_limit {
    // raise [snapshots] max_workspace_gb or shrink/exclude content first
}

Type guard

fn is_workspace_too_large(e: &std::io::Error) -> bool {
    e.kind() == std::io::ErrorKind::InvalidInput && e.to_string().contains("workspace too large for snapshots")
}

Prevention

When it happens

Trigger: Opening snapshots on a workspace whose non-excluded content is larger than the configured GB cap or has more entries than the walk limit, at the moment the side .git snapshot repo does not yet exist (first snapshot enable on this workspace).

Common situations: Pointing Codewhale at a monorepo or a directory containing large vendored artifacts, node_modules-heavy trees without excludes, datasets, or VM images; lowering max_workspace_gb and wiping the snapshot repo; upgrading with a larger default entry limit changed.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/8f9497f351371342. Report an issue: GitHub.