Skip to content

Troubleshooting Common Installation and Setup Issues

This guide covers common problems when building or running MONICA from source, using the Windows installer, running the Docker image, or using the optional Python example scripts.

Build and Installation Issues

Error: cmake: command not found

Cause: CMake is not installed or is not available on PATH.

Fix: Install CMake using the operating system's package manager or from the official documentation: https://cmake.org/download/

Verify the installation:

cmake --version

Error: Compiler or dependency errors during configuration

Cause: MONICA requires a C++17-compatible compiler and external libraries including ZeroMQ and Cap'n Proto.

Fix: For a source build, also make sure the required repositories and submodules are available. See the build instructions in the repository README.

Typical commands are:

git clone --recurse-submodules https://github.com/zalf-rpm/monica.git
cd monica

sh create_cmake_release.sh
cd _cmake release
make

If CMake cannot find a dependency, verify that the dependency was installed through the configured package manager or vcpkg setup.

Error: monica-run: command not found

Cause: The executable was either not built or its directory is not on PATH.

Fix: Run it using its explicit path:

./_cmake_release/monica-run -o output.csv installer/Hohenfinow2/sim-min.json

On Windows, use the executable generated by the selected Visual Studio configuration, for example:

.\_cmake_win64\Release\monica-run.exe -o output.csv .\installer\Hohenfinow2\sim-min.json

If MONICA was installed using the Windows installer, restart the terminal after installation so that the updated PATH and PYTHONPATH values are loaded.

Python and Example-Script Issues

Python is not required to run the native monica-run executable.

It is required for selected examples, including the producer/consumer pipeline in:

installer/Hohenfinow2/python/

Error: ModuleNotFoundError

Cause: This usually affects an example script rather than the MONICA executable.

Fix: Activate the Python environment used for the example and install the dependencies documented by that example or deployment.

Use the interpreter associated with the active environment:

python -m pip install <package-name>

Check which Python is being used:

python --version
python -c "import sys; print(sys.executable)"

Python version compatibility

Python compatibility depends on the specific example scripts and their external packages.

If a Python example fails, first check:

python --version
python -m pip list

Then follow the dependency instructions for that specific example.

Virtual environment activation

On Windows PowerShell:

python -m venv monica-env
.\monica-env\Scripts\Activate.ps1

On Windows Command Prompt:

python -m venv monica-env
monica-env\Scripts\activate.bat

On Linux:

python3 -m venv monica-env
source monica-env/bin/activate

Recreating a broken virtual environment

Only remove the environment if it is disposable and does not contain user data.

Linux:

rm -rf monica-env
python3 -m venv monica-env
source monica-env/bin/activate

Windows PowerShell:

Remove-Item -Recurse -Force .\monica-env
python -m venv monica-env
.\monica-env\Scripts\Activate.ps1
Parameter and Configuration Issues

MONICA simulations commonly use:

  • sim.json for simulation settings
  • crop.json for crop and rotation settings
  • site.json for soil and site settings
  • a climate CSV file for weather data

The parameter repository must be available through MONICA_PARAMETERS

Linux:

export MONICA_PARAMETERS=/path/to/monica-parameters

Windows PowerShell:

$env:MONICA_PARAMETERS = "C:\path\to\monica-parameters"

Error: JSON decode or parse errors

Cause: Common causes include:

  • missing commas or brackets
  • invalid comments
  • incorrect string quoting
  • invalid include-from-file paths
  • files being edited with the wrong character encoding

Fix: Validate each JSON file independently:

python -m json.tool sim.json
python -m json.tool crop.json
python -m json.tool site.json

Powershell alternative:

Get-Content .\sim.json -Raw | ConvertFrom-Json
Get-Content .\crop.json -Raw | ConvertFrom-Json
Get-Content .\site.json -Raw | ConvertFrom-Json

Error: Missing parameter files

If a configuration refers to files such as:

"include-file-base-path": "${MONICA_PARAMETERS}"

verify that MONICA_PARAMETERS points to the root of the parameter repository and that the referenced files exist below that directory.

Error: Incorrect configuration linkage

Fix: Check that:

  • sim.json references the intended crop file
  • sim.json references the intended site file
  • sim.json references the intended climate file
  • included parameter files exist
  • relative paths are resolved from the expected working directory

The example configuration can be run with:

./monica-run -o output.csv installer/Hohenfinow2/sim-min.json
Docker Issues

Error: docker: command not found

Cause: Docker is not installed or is not available on PATH.

Fix: Install Docker from: https://docs.docker.com/get-docker/

Verify the installation:

docker --version
docker info

Error: Building the Docker image fails

The repository Docker build downloads source repositories and build dependencies. Confirm that:

  • Docker has network access
  • Docker has sufficient disk space
  • Git submodules can be cloned
  • the Docker daemon is running

Build the image from the repository root:

docker build -t monica .

Error: Starting the container fails

Fix: Inspect the container output:

docker ps -a
docker logs <container_id>

The image starts MONICA through Supervisor. It expects the MONICA data directory to be mounted at /monica_data when external data is required.

Example:

docker run --rm --mount type=bind,src=/path/to/data,dst=/monica_data monica

Error: Docker permission denied on Linux

Fix: If the current user cannot access the Docker daemon, either use the system's approved Docker setup or ask an administrator to add the user to the Docker group.

After a group change, start a new login session.

Error: Port binding errors

The Docker image uses these ports:

Purpose Port
Producer-facing port 6666
Consumer-facing port 7777
Internal proxy input 6677
Internal proxy output 7788

Check whether another container is using the ports:

docker ps

Stop only the container that owns the conflicting ports:

docker stop <container_id>

Alternatively, map the container ports to different host ports:

docker run --rm -p 6666:6666 -p 7777:7777 monica

The internal ports are normally used between processes inside the container and should not be exposed unless required by the deployment.

Error: Container logs are missing

Inspect the container logs first:

docker logs <container_id>

The Supervisor configuration writes its main log to:

/var/log/supervisord.log

If using a custom container or bind mount, ensure that the target log directory is writable.

ZMQ Proxy and Worker Issues

Error: Connection refused

Cause: Usually, the proxy or worker is not running, or the client is connecting to the wrong host or port.

Fix: Check the running processes or container logs:

docker logs <container_id>

For a local build, verify that these executables exist:

monica-zmq-proxy
monica-zmq-server

Start the proxy before connecting workers or clients.

Error: Worker receives no tasks

Fix: Check the following:

  • the proxy is running
  • the worker is connected to the correct proxy hostname
  • the producer is using port 6666
  • the consumer is using port 7777
  • internal proxy ports are 6677 and 7788
  • firewalls allow traffic between the relevant hosts
  • the worker and proxy use compatible configuration

For the Docker Supervisor setup, proxy autostart is controlled by:

monica_autostart_proxies=true

Worker autostart is controlled by:

monica_autostart_worker=true

To override these variables:

docker run --rm -e monica_autostart_proxies=true -e monica_autostart_worker=true monica

Error: Incorrect proxy hostname

In a multi-host deployment, do not use localhost unless the proxy and worker run on the same host or inside the same network namespace.

Use a resolvable hostname or fully qualified domain name, and verify connectivity with the site's approved network diagnostic tools.

Singularity Issues

Before running a .sif image, verify:

  • the image is readable from the compute node
  • required host directories exist
  • bind paths are permitted by the site
  • the image contains the expected MONICA executables
  • network access between proxy and worker nodes is available

Example bind-path check:

singularity exec -B /scratch:/scratch monica.sif ls -la /scratch

If the site requires named instances:

singularity instance list
singularity instance stop <instance_name>

Do not stop an instance unless it belongs to the current MONICA deployment.

Port availability and firewall rules are site-specific. Consult the HPC administrator if workers cannot connect to a proxy.

SLURM and HPC Issues

Error: Job remains pending

Fix: Inspect the queue:

squeue -u "$USER"

For detailed job information:

scontrol show job <job_id>

Common causes include:

  • unavailable or incorrect partition
  • insufficient requested CPUs or memory
  • account or reservation restrictions
  • job priority
  • requested resources not currently available
  • dependency jobs that have not completed

The fix depends on the cluster configuration.

Error: Worker cannot connect to the proxy

Verify:

  • the proxy hostname is resolvable from the worker node
  • the proxy is running
  • the producer and consumer ports match the deployment
  • internal ports match on both sides
  • compute-node firewall rules permit the connection
  • the job allocation has network visibility to the proxy host

Do not assume that localhost refers to the proxy. On a compute node, localhost refers to that compute node itself.

Climate Data Issues

Error: "Climate file not found”

Check:

  • the file path in sim.json
  • the current working directory
  • the file name and capitalization
  • Docker or Singularity bind paths
  • file permissions on the host and inside the container

For the example configuration:

"climate.csv": "climate-min.csv"

The file must be available relative to the configuration's expected working directory or be referenced with a correct path.

Error: Incorrect climate CSV format

MONICA climate files are configured through the climate.csv-options section in sim.json.

Check:

  • the number of header lines
  • the CSV separator
  • column names
  • date format
  • required weather variables
  • units and expected value ranges

The example uses two header lines and comma-separated values:

"climate.csv-options": {
  "no-of-climate-file-header-lines": 2,
  "csv-separator": ","
}

The example climate file contains fields including:

iso-date,tavg,tmin,tmax,wind,globrad,precip,relhumid

Use the climate-file format expected by the MONICA version and configuration being run.

File and Permission Issues

Error: Cannot write the output file

Fix: Ensure that the output directory exists and is writable:

mkdor -p output
touch output/test-file

Then specify an output path in a writable location:

./monica-run -o output/result.csv installer/Hohenfinow2/sim-min.json

Error: Permission denied inside a container

Fix: Check the identity used by the container and the ownership of the mounted directory:

docker exec -it <container_id> id
docker exec -it <container_id> ls -la /monica_data

Ensure that the host directory is writable by the container user or use a deployment-specific directory with appropriate ownership and permissions.

Avoid making broad system directories world-writable.

Useful Diagnostic Information

When reporting an installation or runtime problem, include:

cmake --version
docker --version
python --version

Also include:

  • operating system and version
  • MONICA commit or release version
  • build command
  • complete error message
  • command used to start MONICA
  • relevant sim.json path
  • whether MONICA runs locally, in Docker, or on HPC
  • relevant container or job logs

Do not include passwords, access tokens, private keys, or other sensitive configuration data.