Installation Issues

Resolving Docker, Kubernetes, and network problems during validator installation

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.