Troubleshooting Zoxide: Fixing "No Match Found" and Database Errors
Zoxide is generally a set-and-forget tool, but as your directory history grows, you might encounter specific issues. The most common frustration for users is the zoxide no match found error. While this often simply means "I haven't been there yet," it can sometimes indicate a corrupted database or a misconfigured shell. This guide covers how to debug these issues on various systems, including zoxide arch and zoxide nixos setups.
Understanding "No Match Found"
When you type z foo and get a zoxide no match found response, it means the ranking algorithm (frecency) yielded zero results. This happens for two reasons:
- New Path: You have never visited the directory before.
- Deleted Path: The directory was deleted, but Zoxide tried to jump to it and failed, subsequently removing it from the database (self-healing).
To fix the first issue, ensure your zoxide alias is correctly hooking into your shell to record movements. Run the following to check if Zoxide is tracking your commands:
Cleaning Up Ghost Entries
Sometimes zoxide autocomplete might suggest directories that no longer exist, cluttering your workflow. While Zoxide tries to clean itself, you can force a cleanup.
On a rolling release like zoxide arch, where you might frequently move large project folders, ghost entries are common. You can remove a specific path manually:
This ensures that your zoxide autocomplete list remains relevant and fast.
Platform-Specific Debugging
For zoxide nixos users, issues often arise from the read-only nature of the Nix store or environment variable conflicts. If Zoxide forgets your history after a reboot, check where _ZO_DATA_DIR is pointing. In a NixOS home-manager setup, ensure your state version is compatible.
If you still encounter zoxide no match found errors despite visiting directories, check your exclusion list. Zoxide ignores certain temporary directories by default. Configuring the environment properly ensures the zoxide alias captures the paths you actually care about.