Installation Issues

Troubleshooting Nix, Docker, and memory problems when setting up Canton Network development

This page covers common installation problems you may encounter when setting up a Canton Network development environment, including Nix shell failures, Docker configuration, and memory allocation.

Nix Problems

Nix shell fails to start

If nix-shell exits with a hash mismatch or download error, your local Nix cache may be stale.

# Clear the Nix store cache for the affected derivation
nix-collect-garbage -d

# Retry
nix-shell

When nix-shell hangs during evaluation, check that your NIX_PATH is set correctly and that no conflicting Nix channels exist:

nix-channel --list

Remove any unexpected channels and re-run nix-shell.

”command not found: nix” after installation

Your shell profile may not source the Nix environment. Add the following to your ~/.bashrc or ~/.zshrc:

source ~/.nix-profile/etc/profile.d/nix.sh

Alternatively, restart your terminal session entirely. On macOS, after a system update Nix sometimes needs reinstallation:

# Uninstall first
/nix/nix-installer uninstall

# Reinstall from https://nixos.org/download

PATH conflicts between Nix and system packages

If a system-installed tool (e.g., a different Java version) takes precedence over the Nix-provided one, verify your PATH ordering:

which java
# Should point to /nix/store/... if using nix-shell

Inside nix-shell, Nix prepends its paths to $PATH. If you still see system binaries, check whether your shell profile appends paths after Nix or overrides them.

Docker Configuration

Insufficient memory for LocalNet

LocalNet runs a full Canton topology locally and needs significant resources. If containers crash with OOM (Out of Memory) kills or fail to start, increase Docker’s memory allocation.

Minimum requirements for LocalNet:

• Memory: 16 GB
• CPU: 4 cores
• Disk: 50 GB free

Docker Desktop: Settings > Resources > set Memory to 16 GB or higher, then Apply & Restart.

Colima (macOS):

colima stop
colima start --memory 16 --cpu 4

Volume mount permission errors

On Linux, Docker containers may fail to write to mounted volumes if your user ID does not match the container’s expected UID. Fix this by ensuring the host directory has appropriate permissions:

chmod -R 777 .data/

Or run Docker with the --user flag matching your host UID:

docker compose run --user "$(id -u):$(id -g)" <service>

Docker Compose version mismatch

Canton Quickstart requires Docker Compose 2.26.0 or higher. If you see:

'env_file[1]' expected type 'string', got unconvertible type 'map[string]interface {}'

Upgrade Docker Compose:

docker compose version  # Check current version

# macOS with Homebrew
brew install docker-compose

# Or update Docker Desktop to the latest version

Memory Allocation

JVM heap for sandbox

The Daml sandbox runs on the JVM and defaults to conservative heap settings. If you encounter java.lang.OutOfMemoryError: Java heap space, increase the heap:

export JAVA_OPTS="-Xmx4g -Xms2g"
dpm sandbox

OOM kills on LocalNet

When Docker kills containers silently, check for OOM events:

docker inspect <container_name> --format='{{.State.OOMKilled}}'

If this returns true, you need to increase Docker’s memory allocation (see the Docker section above). You can also check system-level OOM events:

dmesg | grep -i "out of memory"

Resource limits summary

Environment	Min Memory	Recommended Memory	Min CPU
Sandbox only	4 GB	8 GB	2 cores
LocalNet	16 GB	24 GB	4 cores
cn-quickstart	8 GB	16 GB	4 cores

Before running cn-quickstart, you must execute make setup and make build before make start. Skipping these steps causes startup failures that can look like resource problems.