Documentation/canton-network-docsView on canton-network-docs ↗
canton-network-docs

Installation Issues

Installation Issues - Canton Network Docs
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.

Installation failures typically fall into three categories: container runtime issues, Kubernetes provisioning problems, or network-level blocks that prevent your validator from reaching the synchronizer.

​
Docker Issues

​
Image Pull Failures

If docker compose up fails with an image pull error: 
Error response from daemon: pull access denied for digitalasset/canton-participant
Possible causes:
  • You are not logged in to the container registry. Run docker login digitalasset-docker.jfrog.io with your JFrog credentials.
  • Your JFrog account does not have access to the required repositories. Request access through support.digitalasset.com.
  • A typo in the image tag. Verify the image name and version in your docker-compose.yaml or .env file against the release notes.

​
Resource Limits

Containers that crash immediately or show OOMKilled status need more memory. 
# Check if any container was OOM-killed
docker inspect --format='{{.State.OOMKilled}}' <container_name>
Minimum resource requirements for a validator:
  • Memory: 8 GB allocated to Docker
  • CPU: 4 cores
  • Disk: 50 GB free
For Colima users on macOS: 
colima stop
colima start --memory 8 --cpu 4 --disk 100

​
Volume Permission Errors

If a container fails with permission denied errors on mounted volumes: 
java.io.IOException: Permission denied: /data/canton
The container user (typically UID 1000) must have write access to the host directory. Fix this with: 
sudo chown -R 1000:1000 ./data

​
Kubernetes Issues

​
Helm Chart Errors

Common Helm failures during helm install or helm upgrade:
  • Error: INSTALLATION FAILED: cannot re-use a name that is still in use — A previous release exists. Use helm upgrade instead, or uninstall first with helm uninstall validator -n validator.
  • Error: template: splice-validator/templates/...: ... not defined — Your values file references a variable that does not exist in this chart version. Compare your validator-values.yaml against the chart’s values.yaml for the target version.
# Inspect the chart's default values
helm show values splice-validator/splice-validator --version 0.5.4

​
PVC Provisioning Failures

If pods remain in Pending state, check PersistentVolumeClaim (PVC) events: 
kubectl describe pvc -n validator
Common causes:
  • The StorageClass does not exist in your cluster. List available classes with kubectl get storageclass.
  • Insufficient disk quota in your cloud provider account.
  • The requested storage size exceeds available capacity.

​
Init Container Failures

If the main container never starts, an init container may be failing: 
kubectl logs -n validator <pod-name> -c init-db --previous
Init containers commonly fail due to database connectivity issues — the PostgreSQL instance is unreachable or the credentials are wrong.

​
Image Pull Secrets

Kubernetes needs explicit credentials to pull from private registries: 
kubectl create secret docker-registry jfrog-creds \
  --docker-server=digitalasset-docker.jfrog.io \
  --docker-username=$JFROG_USER \
  --docker-password=$JFROG_TOKEN \
  -n validator
Then reference jfrog-creds in your validator-values.yaml under imagePullSecrets.

​
Network Issues

​
DNS Resolution

If your validator cannot resolve synchronizer hostnames: 
# From inside a Kubernetes pod
kubectl exec -n validator deployment/validator-app -- nslookup sequencer.sync.global
If DNS fails, check your cluster’s CoreDNS pods and any custom DNS configuration.

​
Firewall Rules

Your validator needs outbound access on the following ports:
  • 443 (HTTPS/gRPC-TLS) — to the synchronizer sequencer
  • 5432 — to your PostgreSQL database (if external)
  • 443 — to your OIDC provider (if using authentication)
Test connectivity: 
nc -zv sequencer.sync.global 443
nc -zv sequencer.test.sync.global 443
If connections time out, work with your network team to open the required egress rules. For DevNet, you also need VPN connectivity to the DevNet sequencer.
Assistant
Responses are generated using AI and may contain mistakes.