Skip to content

Troubleshooting

Jump to bottom
jenkin edited this page May 28, 2026 · 2 revisions

Troubleshooting

When something goes wrong, cargo-fresh tries to print a Hint: line below the error with a concrete next step. This page expands on the most common failure modes — what they look like, what's actually happening, and what to do.

"error: cargo install --list failed"

error: `cargo install --list` failed: ...
   Hint: Is `cargo` on your PATH? Try `cargo --version` to verify the toolchain.

cargo-fresh shells out to cargo install --list as its first step. If that command can't run, cargo-fresh can't continue.

Common causes:

  1. cargo not on PATH. which cargo should return a path.
  2. Cargo home is corrupted. Check ~/.cargo/.crates.toml exists and is non-empty.
  3. Permission issue on cargo home. ls -la ~/.cargo/.crates.toml.

Fix: Run cargo --version first. If that fails, fix cargo before retrying cargo-fresh.

"Network connect/timeout. ..."

error: error sending request for url (https://index.crates.io/...): connect timeout
   Hint: Network connect/timeout. Check connectivity to index.crates.io,
         or set HTTPS_PROXY if behind a proxy.

The sparse index request couldn't reach index.crates.io.

Diagnostic steps:

  1. Can you reach the index manually? 
    curl -I https://index.crates.io/ca/rg/cargo-fresh
# Should return HTTP 200
  2. Behind a corporate proxy? Set HTTPS_PROXY: 
    export HTTPS_PROXY=http://proxy.corp:8080
  3. Using a mirror that's down? Try forcing the upstream: 
    cargo fresh --registry-url https://index.crates.io
  4. Want to see what's happening without the search fallback masking it? 
    cargo fresh --no-cargo-search-fallback --verbose

"Why is everything slow / why is this hitting cargo search?"

By default, when sparse index requests fail, cargo-fresh transparently falls back to cargo search per package — which spawns a cargo subprocess each time and is much slower (~1s/package vs ~50ms/package).

Symptoms: Checking takes >10s for a small number of packages.

Confirm the fallback is the cause:

cargo fresh --no-cargo-search-fallback --verbose

With the fallback disabled and --verbose on, sparse index failures become visible errors instead of silent slowness.

Common causes:

  • Mirror configured but unreachable ($CARGO_HOME/config.toml replace-with points somewhere wrong)
  • DNS issue specific to index.crates.io while general network works
  • Mirror is git-style instead of sparse+URL — cargo-fresh only speaks the sparse protocol

"Why are my --check-prebuilt runs flaky / suddenly slow?"

cargo-fresh resolves prebuilt assets via the GitHub Releases API. The anonymous quota is 60 requests/hour per public IP. Hit the limit and the API starts returning 403, at which point cargo-fresh transparently falls back to HEAD-probing 6–24 candidate URLs per package — slower, and counts against GitHub's general abuse heuristics.

Symptoms: --check-prebuilt was sub-second per package yesterday and is suddenly multi-second today; verdicts come back as [unknown] for packages that previously resolved.

Fix: Expose a token. The lookup order is GITHUB_TOKEN → GH_TOKEN → gh auth token from the GitHub CLI. With any of these set, the quota jumps from 60/hr to 5000/hr.

export GITHUB_TOKEN=ghp_...
# or
gh auth login

Tokens are never echoed in cargo-fresh's output, progress lines, or --verbose logs.

"Skip [unknown source]" 

   Skip exotic-tool 0.1.0 [unknown source]

cargo install --list reported a source prefix cargo-fresh doesn't recognize. The package was installed from somewhere other than crates.io, git, or a local path — perhaps an alternate registry not configured as a replace-with.

This is not an error, just a skip. cargo-fresh deliberately won't try to update something whose origin it can't classify.

If you think this is wrong: Open an issue with the line as it appears in cargo install --list output. Format like:

some-tool v0.1.0 (alt+something://...):

parse_source in src/package/mod.rs may need to learn that prefix.

"Slow running for 35s ..." 

   Slow huge-monorepo-tool building for 35s ...

A package has been compiling/installing for >30s. This isn't an error — it's the SlowGuard watchdog letting you know cargo is still working. cargo-fresh hasn't deadlocked.

If it keeps going forever: Hit Ctrl-C (cargo-fresh handles SIGINT and prints an Aborted line). Then try --dry-run to see what command was actually running, and run it manually to see cargo's full output.

"Updated " but the version didn't change 

   Unchanged some-tool 1.0.0

cargo-fresh ran cargo install (or the in-process downloader) successfully but the installed version is identical to what was already there. This happens when:

  1. crates.io served the same version again (race / cache)
  2. Local install picked up a different toolchain than expected
  3. The downloader fetched a binary that had a slightly different version string

Usually safe to ignore. Re-run cargo-fresh to confirm the package shows as fresh now.

"Failed " with exit code 101 

   Failed huge-tool exit code 101 (attempt 3/3)

cargo install returned a non-zero exit. cargo-fresh retries 3 times with 2s backoff before giving up. After 3 failures, the package is marked failed in the summary and cargo-fresh exits with code 2.

Diagnostic steps:

  1. Run with --dry-run to get the exact command: 
    cargo fresh --filter huge-tool --dry-run
  2. Run that command directly — you'll see cargo's full error output (cargo-fresh's spinner hides it).
  3. Common causes:
    • Missing system dependencies (openssl-sys needing libssl-dev, etc.)
    • Out of disk space in ~/.cargo
    • Network blip during dependency fetch
    • MSRV mismatch: the new version requires a newer rustc than you have

Spinner "frames" left on screen

⠋ updating ripgrep ⠋ updating ripgrep

If you see ghost spinner characters after cargo-fresh exits, that's a regression — PbGuard is supposed to call finish_and_clear() on every return path. Please file an issue with the exact terminal you're using (term + version) and what command you ran.

Workaround: reset or clear in your shell.

"interactive prompt doesn't work over SSH"

If cargo fresh (without --batch or --no-interactive) hangs after showing candidates, dialoguer is probably waiting for keyboard input on stdin that isn't connected. cargo-fresh detects this in most cases and downgrades, but exotic SSH setups can confuse it.

Workaround: Always pass --batch or --no-interactive for non-tty runs. The non-TTY detection only handles stderr (for the spinner); the interactive prompt path doesn't auto-downgrade.

"What does each verb mean?"

Verb When you see it
Checking Starting the version check phase
Found N N packages were discovered from cargo install --list
Fresh Package is already at the latest version
Updating Update candidate; will install if selected
Updated Install succeeded, version moved forward
Unchanged Install ran but version didn't change
Skip Package skipped (today: only [unknown source])
Slow 30s elapsed on this package, just letting you know
Would run --dry-run command preview
Fallback downloader unable to find a prebuilt asset; falling back to cargo install
Prebuilt / Compiled End-of-run summary grouping each package by install path
Note Non-fatal informational message
Hint Actionable suggestion after an error
Check / Latest --verbose per-package check details
Package N/M counter during multi-package updates
Failed This package's install failed (after retries)
Aborted User pressed Ctrl-C; partial progress shown
Finished Final summary line

Color reinforces the meaning: green = good, yellow = warning, red = bad, dim = secondary.

When the Hint: line is wrong or missing

The hint matcher in src/errors.rs covers only a few specific failure modes. If you hit an error that didn't get a hint and you wish it had, please report:

  1. The exact error message
  2. What you'd want the hint to say

Each new hint variant is a small, additive PR.

Clone this wiki locally