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
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 -c conda-forge --force-reinstall conda-exec
“solver not available” error#
conda exec: no conda solver backend is available
Recent conda installations provide a default solver backend. If this error appears, the backend is missing, broken, or the configured solver name does not match an installed backend.
Repair the environment that provides your conda command:
conda install -n base -c conda-forge conda
If your installation manages solver plugins separately, install a conda solver
plugin supported by that installation and check the configured solver value in
.condarc.
“invalid match spec” error#
conda exec: invalid match spec for tool '<spec>': <detail>
The tool argument is parsed as a conda match spec. Common causes are unquoted shell characters or invalid conda spec syntax.
Quote version constraints:
conda exec "ruff>=0.4,<0.5" check .
Use --with for extra packages instead of appending them to the tool
argument:
conda exec --with pytest ruff check tests/
“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-exec does not currently support installing package foo while
running executable bar in tool mode. Use a script or a named environment
for that package layout.
“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 -c conda-forge 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
Later runs reuse the cache when the dependency input is unchanged. 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 .
Stale or unusable script lock data#
conda exec: warning: ignoring unusable sidecar lock data: script lock error: <detail>
The lockfile was discovered, but conda could not create an environment from it. If the script still has metadata, conda-exec falls back to solving from the metadata.
Refresh the lock:
conda exec --lock --refresh script.py
Or bypass the lock for one run:
conda exec --ignore-lock script.py