Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• src/executor.rs
• src/config.rs
• src/main.rs
• src/init.rs
• src/resolution_state.rs
• README.md

This page provides technical guidance for diagnosing and resolving issues encountered when using cargo-cooldown. Troubleshooting primarily involves understanding the interaction between Cargo's resolution graph, cooldown enforcement policies, and the local registry metadata.

The system is designed to "fail closed" by default under strict enforcement, restoring the original Cargo.lock if a safe resolution cannot be found. This ensures that a compromised or unstable lockfile is never persisted to the workspace.

Configuration and Setup Issues

Issues often arise during the initialization phase or when configuration precedence leads to unexpected behavior.

Initialization Errors

The cargo cooldown init command is an interactive wizard designed to create cooldown.toml files. It performs project discovery to identify if the target is a single crate or a workspace.

• Overwrite Prevention: The tool explicitly refuses to overwrite existing cooldown.toml files to prevent accidental loss of configuration.
• Project Root Requirement: cargo cooldown init must be run from the project root. It will fail if invoked from a subdirectory that is not a workspace or crate root.
• Command Confusion: Users often mistake cargo cooldown init for Cargo's project generator. cargo-cooldown includes logic to detect and warn if flags like --bin are passed, which are specific to cargo init.

Sources: src/init.rs:48-60, src/main.rs:160-165, src/main.rs:410-415

Configuration Precedence

Configuration is merged from multiple sources. If settings are not behaving as expected, check the following hierarchy (strongest to weakest):

1. Environment Variables: Prefixed with COOLDOWN_ (e.g., COOLDOWN_MINUTES).
2. Member-specific Config: cooldown.toml in a workspace member directory (only applies when that member is the unique target).
3. Workspace/Root Config: cooldown.toml at the project root.
4. Global Config: $CARGO_HOME/cooldown.toml.

Sources: src/config.rs:88-100, README.md:68-75

Dependency Resolution Failures

The most complex troubleshooting area involves cases where cargo-cooldown cannot find an older compatible version of a crate.

Enforcement Policies

The behavior of the tool upon finding "fresh" crates (those within the cooldown window) depends on the enforcement setting.

Enforcement	Behavior on Unresolved Fresh Crate
strict	Fails the command and restores the original Cargo.lock.
cargo_compatible	Issues a warning and allows the Cargo command to proceed with the fresh version.
off	Bypasses all cooldown checks.

Sources: src/config.rs:17-30, src/executor.rs:271-285

Solver Logic and Blocker Pruning

When the "Batch Solver" fails to resolve a set of crates, it attempts to identify "blockers"—specific packages that constrain the graph such that no older version satisfies all requirements.

Coordinated Bundle Issues

Some crates are linked by "exact" requirements (=x.y.z). These cannot be cooled individually. cargo-cooldown attempts a "Coordinated Bundle Resolution" for components up to 8 crates. If a bundle is larger than this or contains duplicate crate names, the coordinated attempt is skipped.

Sources: src/executor.rs:1040-1065

Diagnostic Tools

Verbose Logging

Enabling verbose mode (via COOLDOWN_VERBOSE=1 or verbose = true in config) provides detailed insights into:

• Release Time Sources: Whether timestamps came from index_pubtime or registry_api_fallback.
• Cache Status: Hits or misses in the local JSON cache for API responses.
• Solver Decisions: Reasons why specific versions were kept, added, or removed.

Sources: src/executor.rs:114-125, src/resolution_state.rs:198-210

Execution Flow Monitoring

The sequence of operations during a guard-style command (like check or build) vs an update command is critical for diagnosing where a failure occurred.

Common Error Messages

Message Fragment	Cause	Resolution
refusing to overwrite...	cooldown.toml already exists.	Manually edit the existing file or delete it before running init.
strict enforcement blocked...	Fresh versions exist that cannot be cooled.	Switch to cargo_compatible or add an allow rule for that version.
missing release timestamp	Registry index and API both lack pubtime.	Check registry health or add the registry to skip_registries.
must run from the project root	Command run in a subdirectory.	cd to the directory containing the workspace Cargo.toml.

Sources: src/init.rs:58, src/executor.rs:271, src/config.rs:155, tests/init.rs:65

Summary

Troubleshooting cargo-cooldown requires balancing security (enforcing the cooldown) with utility (allowing Cargo to build). Most issues can be resolved by inspecting the verbose logs to see why a candidate was rejected—often due to a lockfile_baseline = "floor" constraint or a strict semver requirement in the Cargo.toml.

Sources: src/executor.rs:1255-1275, src/config.rs:47-58