Troubleshooting¶

This section includes troubleshooting advice for common errors, organized by platform. If you encounter errors that you cannot solve via the standard step-by-step guide or the advice below, contact the developers.

Quick error index¶

General (all platforms)¶

Numerically fragile coupled runs¶

Some coupled atmosphere-interior-outgassing configurations occasionally fail with messages such as RuntimeError: Aragog retry ladder exhausted or with warnings about T_core jumping >1500 K despite Aragog reporting status=0. The same config may succeed on one launch and fail on the next.

The cause is sub-1e-7 floating-point noise in JAX/XLA reduction order that compounds through Aragog's tight tolerances and lands the solver on a wrong P-S branch within ~15 iterations.

Workaround: launch PROTEUS with --deterministic:

nohup proteus start -c <cfg.toml> --offline --deterministic \
    > output/<run>/launch.log 2>&1 & disown

The flag intercepts itself in sys.argv before any heavy imports, sets JAX_ENABLE_X64=1 and XLA_FLAGS=--xla_cpu_enable_fast_math=false, and self-re-execs once. PROTEUS already pins BLAS thread counts at import time; --deterministic adds the JAX/XLA layer that BLAS pinning alone does not cover.

Do not enable by default; the flag has a small per-step cost. Use only when a config shows noise-floor divergence between launches.

For broader convergence problems,see stabilising simulations.

Cannot clone module, or Permission denied (publickey)¶

Have you added your SSH key to GitHub? See these pages for guidance:

• Checking for existing SSH keys
• Generating a new SSH key
• Adding a new SSH key to your Github account
• Testing your SSH connection

Out-of-date modules detected¶

You will see an error that looks like this:

[ INFO  ] Validating module versions
[ ERROR ] (MODULENAME) module is out of date: (INSTALLED VER) < (REQUIRED VER)
Uncaught exception
    ...
OSError: Out-of-date modules detected. Refer to the Troubleshooting guide on the wiki

This means one of the required PROTEUS modules is outdated on your machine. You need to update the named module before running PROTEUS again.

You can check which modules are out of date by running:

proteus doctor

If you have not manually installed this module, go to the PROTEUS folder and run:

python -m pip install -e .

If you have a developer installation of the module, go to the module's own folder and run:

git checkout main
git pull
python -m pip install -U -e .

Data download errors or slow Zenodo downloads¶

PROTEUS automatically downloads input data files from Zenodo. The code works without an API token using public access, but you can optionally configure a token for enhanced rate limits.

PETSc complains about being in the wrong directory¶

First, check that you are in the correct directory when running make or ./configure. If you are, this could be caused by the environment variable PETSC_DIR remaining set after a previous PETSc installation. Run unset PETSC_DIR and try again.

libudev.so.1 not found¶

This happens when compiling SPIDER within a Python environment that is incompatible with PETSc. Try compiling SPIDER (and/or PETSc) in your system's base Python environment, and ensure that you are not using Python >= 3.13, as SPIDER is only supported for Python versions <= 3.12 currently.

Julia compatibility error¶

There are incompatibilities between Python and some versions of Julia. Supported Julia versions are 1.11.x and 1.12.x; newer releases (including the 1.13 release candidates) are untested and may fail when juliacall resolves shared libraries.

You must use Python 3.12 with a supported Julia to avoid these problems:

juliaup add 1.12
juliaup default 1.12

macOS¶

PETSc compilation fails on Apple Silicon¶

The get_petsc.sh script automatically detects Apple Silicon and applies the necessary workarounds. If it still fails, check the following.

Prerequisites

Make sure you have installed GCC and OpenMPI via Homebrew:

brew install gcc open-mpi

Also ensure Xcode Command Line Tools are installed:

xcode-select --install

Common issues

1. Deprecated linker warnings (macOS 13+/clang 15+): PETSc's configure uses -bind_at_load and -multiply_defined flags that are deprecated on modern macOS. The script suppresses these with -Wl,-w.

2. C++ template errors (macOS 26+/clang 17+): PETSc 3.19's CUDA/CUPM headers trigger -Wmissing-template-arg-list-after-template-kw. The script avoids this by disabling C++ (--with-cxx=0), which is safe because SPIDER is pure C.

3. SDKROOT not set: On macOS Catalina and later, system headers are inside the SDK, not /usr/include. The script sets SDKROOT automatically via xcrun --show-sdk-path.

PETSc tests error (network configuration)¶

Error when running the PETSc tests:

Fatal error in PMPI_Init_thread: Other MPI error, error stack:
MPIR_Init_thread(467)...............:
MPID_Init(177).....................: channel initialization failed
MPIDI_CH3_Init(70).................:
MPID_nem_init(319).................:
MPID_nem_tcp_init(171).............:
MPID_nem_tcp_get_business_card(418):
MPID_nem_tcp_init(377).............: gethostbyname failed, localhost (errno 3)

This is a network configuration issue. To fix it, add the following to /etc/hosts, where computername is your hostname:

127.0.0.1   computername.local
127.0.0.1   computername

Then enable Remote Login in your Sharing settings and add your user to the allowed access list.

Errors during PETSc configuration or compilation (x86 header)¶

One of the following errors during PETSc configuration or compilation:

This header is only meant to be used on x86 and x64 architecture
#error "This header is only meant to be used on x86 and x64 architecture

Install Python via Homebrew and use pip to manage packages, rather than Conda.

Errors during the SOCRATES compilation¶

One of the following errors happen during the SOCRATES compilation:

1. clang (LLVM option parsing): Unknown command line argument '-x86-pad-for-align=false'. Try: 'clang (LLVM option parsing) --help'
2. clang (LLVM option parsing): Did you mean '--x86-slh-loads=false'?

There is an issue with your compiler, either the standard Apple clang or gcc installed by brew. Follow the steps provided at the StackOverflow thread:

sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install

FastChem compilation with Apple Silicon¶

With Apple Silicon hardware (M1/M2/M3), the option -march=native sometimes causes issues.

Make sure to use the GNU version of g++, not the Apple one. The Apple version located at /usr/bin/gcc is actually a wrapper around clang.

The Homebrew version located at /opt/homebrew/bin/ works well. Find out which gcc version Homebrew installed (ls /opt/homebrew/bin/gcc-*), and edit the file make.globaloptions in the FastChem directory to use, e.g. g++-12 or g++-13 instead of g++.

Python netCDF library error¶

Error: Library not loaded: '@rpath/libcrypto.3.dylib'

Create a symlink in the local Python installation. See this guide for details.

brew install openssl

Follow the instructions at the end of the openssl installation (replace USERNAME with your own system username):

echo 'export PATH="/usr/local/opt/openssl@3/bin:$PATH"' >> /Users/USERNAME/.bash_profile
echo 'export LDFLAGS="-L/usr/local/opt/openssl@3/lib"' >>/Users/USERNAME/.bash_profile
echo 'export CPPFLAGS="-I/usr/local/opt/openssl@3/include"' >>/Users/USERNAME/.bash_profile
ln -s /usr/local/opt/openssl/lib/libcrypto.3.dylib /Users/USERNAME/opt/anaconda3/envs/proteus/lib/python3.10/site-packages/netCDF4/../../../
ln -s /usr/local/opt/openssl/lib/libssl.3.dylib /Users/$USER/opt/anaconda3/envs/proteus/lib/python3.10/site-packages/netCDF4/../../../

ModuleNotFoundError: No module named 'yaml'¶

Install yaml via pip rather than via conda:

python -m pip install pyyaml

Missing ifort compilers¶

If the SOCRATES installation steps complain about missing ifort compilers:

Install Intel compilers from the Intel oneAPI Toolkit page. First install Intel oneAPI Base Toolkit, then Intel oneAPI HPC Toolkit. Follow the instructions provided after the installation to set the locations of ifort in your environment.

ModuleNotFoundError: No module named '_tkinter'¶

Install the tkinter package using brew:

brew install python-tk

TkAgg backend / X-forwarding error¶

Error: ImportError: Cannot load backend 'TkAgg' which requires the 'tk' interactive framework, as 'headless' is currently running

If you are connecting to a computer over SSH, make sure to enable X-forwarding. This can be done in your SSH configuration file or as a command line parameter. Install XQuartz on your Mac.

YAML library error¶

Error: ld: unsupported tapi file type '!tapi-tbd' in YAML file '/Library/Developer/CommandLineTools/SDKs/MacOSX13.sdk/usr/lib/libSystem.tbd' for architecture arm64

There is an issue with your ld, potentially caused by an existing installation of anaconda. Delete all traces of anaconda by following the steps at the Anaconda uninstall guide, then install Python via brew.

gfortran cannot find system libraries¶

Error: ld library not found for -lsystem

This usually occurs when your operating system has been updated, but Xcode is not on the latest version. Try updating or reinstalling Xcode.

Alternatively, try adding the following flag to the gfortran compile and link steps:

-L/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib/

Linux¶

Cannot compile PETSc on compute cluster¶

There are various reasons that PETSc might have problems compiling. On a cluster, this could be caused by a mismatch between your MPICH version and SLURM. This is a known problem on Snellius.

Try loading the OpenMPI module:

module load mpi/openmpi-x86_64

Cannot compile PETSc, error moving libraries (Fedora/RHEL)¶

If you are using Fedora or RedHat Linux distributions, you might encounter an error:

Error moving
  /home/$USER/PROTEUS/petsc/arch-linux-c-opt/externalpackages/f2cblaslapack-3.8.0.q2
  libraries

To resolve, follow these steps:

1. Install libraries:

   sudo dnf install lapack lapack-devel lapack-static sundials-mpich \
       openmpi openmpi-devel f2c f2c-libs
   

2. Enable module utility: source /etc/profile.d/modules.sh
3. Load OpenMPI module: module load mpi/openmpi-x86_64
4. Add the commands from steps 2 and 3 to your ~/.bashrc file.
5. Run the get_petsc.sh script again.

netcdff.so not found¶

This happens when SOCRATES cannot find the NetCDF-Fortran library. Make sure that it's installed. You can also try adding the library location to your LD_LIBRARY_PATH variable. Find the location of the NetCDF-Fortran library using:

nf-config --flibs