Skip to content

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

Error / symptom Section
Permission denied (publickey) SSH keys
Out-of-date modules detected Module updates
Slow Zenodo downloads Data downloads
libudev.so.1 not found libudev
OpenSSL_jll / Julia error Julia compatibility
PETSc fails on Apple Silicon PETSc Apple Silicon
x86-pad-for-align / SOCRATES SOCRATES compilation
libcrypto.3.dylib not found netCDF error
PETSc error moving libraries Fedora/RHEL PETSc

General (all platforms)

Cannot clone module, or Permission denied (publickey)

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

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.

Optional: Configure a Zenodo API token

If you encounter rate limiting errors or slow downloads, you can set up a Zenodo API token:

  1. Get a personal access token from Zenodo
  2. Configure it: 
    pystow set zenodo api_token <your-token>
  3. Verify it's configured: 
    pystow get zenodo api_token

The token is optional. PROTEUS uses public access by default and falls back gracefully if the token is unavailable.

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. Julia version 1.12+ is not yet supported because it requires a version of the OpenSSL library that is incompatible with Python.

You must use Python 3.12 and Julia 1.11 to avoid these problems:

juliaup add 1.11
juliaup default 1.11

macOS

PETSc compilation fails on Apple Silicon

Applies to: macOS on Apple Silicon (M1, M2, M3, Ultra)

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.

Manual fix (if the script does not work)

  1. Set environment variables:

    export SDKROOT=$(xcrun --show-sdk-path)

  2. Navigate to petsc/ and run the configure command manually:

    cd petsc
./configure \
   PETSC_ARCH=arch-darwin-c-opt \
   LDFLAGS="-L$(brew --prefix)/lib -Wl,-w" \
   --with-debugging=0 \
   --with-fc=0 \
   --with-cxx=0 \
   --download-sundials2 \
   --COPTFLAGS="-g -O3"

  3. Build and test:

    make PETSC_DIR=$(pwd) PETSC_ARCH=arch-darwin-c-opt all
make PETSC_DIR=$(pwd) PETSC_ARCH=arch-darwin-c-opt check

Tested on M1 Ultra (macOS 15.6.1), M2 (macOS 26.2), and M4 Max (macOS 26.3).

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