Troubleshoot common issues#

Tip

Most cache-related problems are fixed by running conda exec --refresh TOOL ..., which discards the cached environment and creates a fresh one. Try this first before deeper debugging.

“command not found” after install#

If conda exec is not recognized after installing conda-exec, the plugin may not be loaded. Verify the installation:

conda list -n base conda-exec

If it is installed but still not found, check that conda-rattler-solver is also installed. conda-exec requires it:

conda install -n base conda-rattler-solver

The standalone ce command should work independently of the plugin system. If conda exec fails but ce works, the plugin entry point is not being discovered. Reinstalling conda-exec usually fixes this:

conda install -n base --force-reinstall conda-exec

“solver not available” error#

conda exec: conda-rattler-solver is required but not installed

Install the solver backend:

conda install -n base conda-rattler-solver

“binary not found” error#

conda exec: binary 'foo' not found in cached environment

The package was installed, but it does not provide a binary matching the package name. This happens when the package name differs from the executable name.

Inspect what the package actually provides:

conda exec --list

Check the package contents to find the correct binary name:

conda search --info foo

“conda-pypi required” error#

conda exec: script declares PyPI dependencies but conda-pypi is not installed

Your script has a top-level dependencies field (PyPI packages) in its PEP 723 metadata, but conda-pypi is not available. Install it:

conda install -n base conda-pypi

Alternatively, move your dependencies to [tool.conda].dependencies if they are available as conda packages, which does not require conda-pypi.

Slow first run#

The first invocation of a tool is slow because conda-exec must:

Resolve dependencies using the solver
Download packages
Extract and install them into the cached environment

Subsequent runs reuse the cache and start instantly. To see existing cached environments:

conda exec --list

Cache corruption#

If a cached environment is broken (e.g., from an interrupted download or disk issue), force re-creation:

conda exec --refresh ruff check .

To remove all cached environments and start fresh:

conda exec --clean --all --yes

Permission denied (exit code 126)#

conda exec: ruff: permission denied

Warning

Re-creating an environment with --refresh removes any manual customizations made to that cached environment. If you have added files or modified the environment by hand, back them up first.

The binary exists but is not executable. This can happen if the cached environment was copied from another system or if file permissions were altered. Fix it by re-creating the environment:

conda exec --refresh ruff check .

Tool not found (exit code 127)#

conda exec: ruff: command not found

The binary could not be executed. This typically means the executable was deleted from the cached environment or there is a platform mismatch. Re-create the environment:

conda exec --refresh ruff check .

If the problem persists, clean the cache entirely:

conda exec --clean --all --yes
conda exec ruff check .