Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.canton.network/llms.txt

Use this file to discover all available pages before exploring further.

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

EnvironmentMin MemoryRecommended MemoryMin CPU
Sandbox only4 GB8 GB2 cores
LocalNet16 GB24 GB4 cores
cn-quickstart8 GB16 GB4 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.