Troubleshooting & FAQs

This page collects common problems users encounter when working with E3SM-Unified and how to resolve them. If you encounter an issue not listed here, please reach out via Slack or GitHub.

Common Issues

“Permission Denied” When Installing E3SM-Unified

Symptom:

OSError(13, 'Permission denied')

Cause: You’re likely trying to install E3SM-Unified into a system-wide Python or Conda environment you don’t have write access to.

Solution: Install Miniforge3 in your home directory and create an environment locally, see Quickstart Guide.

“Module Not Found” When Importing Packages

Symptom:

ModuleNotFoundError: No module named 'e3sm_diags'

Cause: E3SM-Unified may not be activated correctly, or you’re in a different shell/session.

Solution: Re-source the appropriate load_latest_e3sm_unified_<machine>.sh script and retry.

If you installed E3SM-Unified locally, confirm that your active environment contains the package:

conda list e3sm-unified

MPI-based Tools Fail on Login Nodes

Symptom: Tools like mpas_analysis or nco crash with MPI errors.

Cause: These tools may require the hpc package variant or another MPI-enabled stack that is intended for compute nodes.

Solution: Launch a batch job or an interactive compute session with srun, salloc or qsub, depending on your machine.

If you are on an HPC machine, confirm the active deployment mode:

echo "$E3SMU_MPI"

If this prints NOMPI on a compute node, the load script may have selected the login environment instead of the compute-node environment.

Local Install Solves to the Wrong Package Variant

Symptom: You expected MPI-enabled tools but installed the default package.

Cause: conda create -n e3sm-unified e3sm-unified will typically resolve to the default nompi variant unless you constrain the build string.

Solution: Create a fresh environment and request the desired variant explicitly, for example:

conda create -n e3sm-unified -c conda-forge python=3.13 "e3sm-unified=*=mpi_mpich_*"

Tips & Best Practices

  • Always check you’re in the correct conda environment.

  • On HPC systems, prefer running MPI-enabled tools on compute nodes.

  • If installing locally, make sure have create a clean environment with the latest version of E3SM-Unified.

  • Refer to the Quickstart Guide for environment setup instructions.

Still Need Help?

Support