Skip to main content
Version: 0.6.x

Troubleshooting

This guide covers common problems with poof. For a useful first check, run poof info to see the detected platform and managed directories, and poof check to check whether poof's bin directory is available in PATH.

When a problem persists, rerun the failing command with debug logging:

RUST_LOG=debug poof install owner/repository 2>&1 | tee poof-debug.log

Replace the example command with the one that failed. See Debug Logs for more ways to capture diagnostic output.

GitHub lookup or download fails​

Check that the repository is written as owner/repository, that you can reach GitHub, and that the repository has a release. If GitHub reports a rate limit, configure GITHUB_TOKEN and follow the Rate Limiting guide.

No compatible release asset is found​

Poof selects release assets for the current operating system, CPU architecture, and Linux libc preference. Confirm that the project publishes a compatible asset and review Supported Platforms and How It Works.

Archive validation or extraction fails​

The release asset may be corrupted, use an unsupported format, or have a filename that does not match its contents. Try again or check the release page for a valid asset. Poof validates archive type and applies extraction limits for safety.

An installed command is missing or the wrong version runs​

Run poof check to inspect PATH. If the managed bin directory is missing, follow Shell Configuration. Use poof list to inspect installed repositories, poof which <binary> to locate a binary, and poof what <repository> to inspect the binaries provided by its highest-sorting installed version. Use poof list <repository> to inspect its installed versions.

Version selection or update fails​

Check that the repository is installed and that the requested release tag exists. Use poof list to review installed versions. For a fresh install, confirm the release tag on the repository's GitHub Releases page.

Poof cannot read or write managed files​

Run poof info to see the data, cache, and binary directories in use. Check that your account can access those paths and has space available. See Data Storage for the platform-specific locations.

Reporting a bug​

If these steps do not resolve the issue, report it with:

  • The exact command and complete error output
  • Output from poof info
  • Your operating system and architecture
  • Debug output from the failing command