xai-org/grok-build · error

could not reserve a unique {kind} artifact

Error message

could not reserve a unique {kind} artifact

What it means

ManagedConfigError::Write wrapping an io::Error of kind AlreadyExists, raised when a transaction cannot reserve a unique artifact filename for a {kind} item. The reserve helper retries candidate paths and gives up when every candidate already exists, indicating pathological name-collision or an exhausted namespace. It surfaces as a write failure on the target path.

Source

Thrown at crates/codegen/xai-grok-config/src/managed_text/transaction.rs:272

            use std::os::unix::fs::OpenOptionsExt as _;
            options.mode(mode);
        }
        #[cfg(not(unix))]
        let _ = mode;
        match options.open(&candidate) {
            Ok(file) => return Ok((candidate, file)),
            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
            Err(source) => {
                return Err(ManagedConfigError::Write {
                    path: candidate,
                    source,
                });
            }
        }
    }
    Err(ManagedConfigError::Write {
        path: target.to_path_buf(),
        source: std::io::Error::new(
            std::io::ErrorKind::AlreadyExists,
            format!("could not reserve a unique {kind} artifact"),
        ),
    })
}

fn write_reserved(
    path: &Path,
    file: &mut File,
    bytes: &[u8],
    mode: Option<u32>,
) -> Result<(), ManagedConfigError> {
    file.write_all(bytes)
        .and_then(|()| apply_exact_mode(file, mode))
        .and_then(|()| file.sync_all())
        .map_err(|source| ManagedConfigError::Write {
            path: path.to_path_buf(),
            source,

View on GitHub (pinned to bc7f02eddd)

Solutions

1. Inspect the target directory and prune stale/duplicate {kind} artifacts so a free name exists
2. Check the unique-name generation (counter/timestamp) for wrap-around or constant values
3. Retry the transaction; transient collisions resolve once a unique slot frees
4. If the file exists but should be overwritten, delete it or use a non-reserving write path

Example fix

// before
let artifact = txn.reserve_unique("session")?; // AlreadyExists if all candidates taken
// after
std::fs::remove_file(target.join("session-0001.toml")).ok(); // prune stale artifact
let artifact = txn.reserve_unique("session")?;

let target = &txn.target_dir();
let collisions: Vec<_> = std::fs::read_dir(target)?
    .filter_map(|e| e.ok())
    .filter(|e| e.file_name().to_string_lossy().starts_with(kind))
    .collect();
if collisions.len() > 100 { eprintln!("artifact dir saturated: {} candidates", collisions.len()); }

match txn.reserve_unique(kind) {
    Err(ManagedConfigError::Write { source, .. })
        if source.kind() == std::io::ErrorKind::AlreadyExists =>
        eprintln!("name space exhausted for {kind}; prune artifacts"),
    other => other?,
}

When it happens

Trigger: Calling the managed-config transaction commit/reserve flow when the generated candidate artifact name collides with existing files on every retry iteration (e.g. thousands of same-named artifacts already in the target directory).

Common situations: Runaway accumulation of auto-named artifacts in the config directory; clock/counter sources producing identical names; a read-only or mirrored directory where cleanup never happens.

Related errors

• Failed to set working directory to {:?}: {}
• failed to read {}: {e}
• failed to write {}: {e}
• failed to create chrome trace {:?}: {}
• failed to read {}: {e}

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/a70067bf2226a757. Report an issue: GitHub.