Troubleshooting

Common issues, error messages, and debugging tips for conda

This guide covers common issues you may encounter when using conda and how to resolve them.

Common Issues

Environment Not Found

If you encounter an environment not found error:

Error Message

CondaError: Could not find conda environment: myenv
You can list all discoverable environments with `conda info --envs`.

Package Not Found

The PackagesNotFoundError occurs when conda cannot find a package in the configured channels.

From conda/exceptions.py:740:

class PackagesNotFoundError(CondaError):
    """The following packages are not available from current channels"""

Solutions:

1. Search for alternate channels at anaconda.org
2. Add additional channels:
   conda config --append channels conda-forge
   
3. Check if use_only_tar_bz2 is enabled (may omit packages)

Channel Issues

Channel Not Accessible

Conda validates that channels are accessible and contain valid repodata. File-based channels must include noarch/repodata.json.

# Check your channel configuration
conda config --show channels

# View config file locations
conda config --show-sources

Channel Not Allowed

From conda/exceptions.py:518:

class ChannelNotAllowed(ChannelError):
    """Channel not included in allowlist"""

Check your organization’s channel policies if you encounter this error.

Error Types Reference

Dependency Errors

UnsatisfiableError

Occurs when conda cannot find a combination of packages that satisfies all requirements.

Common causes:

• Conflicting version requirements
• Python version incompatibility
• Strict channel priority removing required packages

Debug tips:

# Enable detailed unsatisfiable hints
conda config --set unsatisfiable_hints True

# Try with channel priority disabled
conda install <package> --channel-priority disabled

CyclicalDependencyError

From conda/exceptions.py:1038:

class CyclicalDependencyError(CondaError, ValueError):
    """Cyclic dependencies exist among these items"""

This indicates a circular dependency in the package graph. Contact package maintainers.

Permission Errors

NotWritableError

The current user doesn’t have write permissions to a required path.

# On Linux/macOS, fix with (use cautiously):
sudo chown $UID:$(id -g) /path/to/conda

# Better: use a user-writable prefix
conda create -p ~/my-envs/myenv

EnvironmentNotWritableError

Cannot modify the target environment due to permission restrictions.

Solutions:

• Use a different environment location
• Request administrator access
• Use --prefix to specify a writable location

Environment Errors

CorruptedEnvironmentError

From conda/exceptions.py:1049:

Corrupted environments commonly occur when the conda process is force-terminated during an unlink-link transaction.

# Remove and recreate the environment
conda remove -n myenv --all
conda create -n myenv python=3.11

Connection and Download Issues

HTTP Errors

1. Check Network Connection

   Verify you can access the internet and conda channels.

2. Proxy Configuration

   From conda/exceptions.py:479:

   class ProxyError(CondaError):
       """Error in proxy configuration"""
   

   Check for typos in:

   • .netrc file in your home directory
   • Environment variables ending in _PROXY
   • System-wide proxy settings
3. SSL/TLS Issues

   # Temporarily disable SSL verification (not recommended for production)
   conda config --set ssl_verify false
   
   # Or specify a custom CA bundle
   conda config --set ssl_verify /path/to/ca-bundle.crt
   

Checksum Mismatch

From conda/exceptions.py:630:

class ChecksumMismatchError(CondaError):
    """Conda detected a mismatch between expected and downloaded content"""

Actions:

1. Retry the operation (temporary network issue)
2. Clear the package cache: conda clean --all
3. Report to the channel maintainer if it persists

Path and File Conflicts

Clobber Errors

Clobber errors occur when conda tries to overwrite existing files.

From conda/exceptions.py:176:

class ClobberError(CondaError):
    """Conda was asked to clobber an existing path"""

Types:

• KnownPackageClobberError: Path collision with another conda package
• UnknownPackageClobberError: Path collision with non-conda file
• SharedLinkPathClobberError: Multiple packages want the same path

Solution:

# Use --clobber flag to override (use cautiously)
conda install <package> --clobber

Debugging Tips

Enable Debug Mode

Command Line

# Run any conda command with verbose output
conda install <package> --debug

# Or with detailed info
conda install <package> --verbose

Collect Environment Information

# Get detailed conda information
conda info --all

# List installed packages
conda list

# Check environment history
conda list --revisions

Use JSON Output

JSON output is useful for programmatic error handling and reporting.

conda search <package> --json
conda list --json
conda info --json

Check Configuration

# Show all configuration values
conda config --show

# Show configuration file sources
conda config --show-sources

# Validate configuration
conda config --validate

Memory and Space Issues

NoSpaceLeftError

Free up disk space or use a different package cache directory:

conda config --add pkgs_dirs /path/with/space

CondaMemoryError

From conda/exceptions.py:1095:

Increase system memory or use a more efficient solver:

conda install <package> --solver libmamba

Command-Specific Issues

Activation Issues

If conda activate doesn’t work, your shell hasn’t been properly configured.

From conda/exceptions.py:299:

class CommandNotFoundError(CondaError):
    """Your shell has not been properly configured to use 'conda activate'"""

Solution:

# Initialize your shell
conda init <SHELL_NAME>

# Supported shells: bash, zsh, fish, tcsh, xonsh, cmd.exe, powershell

# Then restart your shell

Lock Errors

From conda/exceptions.py:73:

class LockError(CondaError, OSError):
    """Another conda process is running"""

Solutions:

1. Wait for the other conda process to complete
2. If stuck, manually remove lock files (use with caution):
   rm -f ~/miniconda3/.conda_lock
   

Getting Help

Community Support

• Conda GitHub Issues
• Conda Discourse Forum

Report a Bug

Include the output of:

conda info
conda list
conda config --show-sources

For emergency recovery, you can always recreate your environment from an exported environment file:

# Export current environment (if accessible)
conda env export > environment.yml

# Later, recreate it
conda env create -f environment.yml