> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-integrate-release.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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...
```

Possible causes:

* A typo in the image tag. Verify the image name and version in your `docker-compose.yaml` or `.env` file against the release notes.
* Stale cached credentials from an old `docker login`.

### Resource Limits

Containers that crash immediately or show `OOMKilled` status need more memory.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

## Network Issues

### DNS Resolution

If your validator cannot resolve synchronizer hostnames:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

## Using the Oracle JDK

When using the Oracle JDK, you may get an error such as the following when executing transactions:

```none theme={"theme":{"light":"github-light","dark":"github-dark"}}
java.lang.SecurityException: JCE cannot authenticate the provider BC
        at java.base/javax.crypto.JceSecurity.getInstance(JceSecurity.java:150)
        at java.base/javax.crypto.Mac.getInstance(Mac.java:272)
        at com.digitalasset.canton.crypto.provider.jce.JcePureCrypto.$anonfun$computeHmacWithSecretInternal$1(JcePureCrypto.scala:873)
        (...)
```

The Canton JAR embeds the BouncyCastle provider, and the Oracle JVM verifies the signature of third-party security providers. Download the [BouncyCastle provider JAR](https://mvnrepository.com/artifact/org.bouncycastle/bcprov-jdk18on) and place it ahead of the Canton JAR on the class path:

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
java -cp bcprov-jdk18on-<version>.jar:./lib/canton-open-source-<canton-version>.jar com.digitalasset.canton.CantonCommunityApp -c <config files...>
```