Skip to main content

Troubleshooting

Start with the health of the connector, which reports every Config Profile separately, and with the log of the failing sidecar, which names the path or setting it could not use. For problems of the Connector resource itself, such as a failed registration or a missing Secret, read its conditions as The Connector CR describes.

SymptomCauseFix
A Config Profile is down while its sidecar runsThe address or configId of the profile does not match the sidecarCompare proxyAddress with the listen address of the sidecar. For SoftHSM, configId is softhsm-default
A sidecar exits with no PKCS#11 module at /opt/pkcs11/module.soThe image is not finalized, or a volume is mounted over the libraryUse the finalized image, and check the volume mounts of the sidecar
A sidecar exits with cannot be loaded by this imageThe base variant or the CPU architecture does not match the vendor libraryBuild on the -rocky base, and schedule the pod on amd64 nodes for Utimaco and nShield
A sidecar exits with unknown module in configThe proxy configuration names a module that the proxy does not provideUse the modules block from the vendor page
A sidecar exits with address already in useTwo sidecars of a Connector resource listen on the same portGive each sidecar its own PKCS11_PROXY_LISTEN_ADDRESS, and update its Config Profile and probes
A vendor sidecar stays in ImagePullBackOffThe pod has no pull secret for the registry of the finalized imageAdd one to imagePullSecrets of the Helm chart, or to spec.image.pullSecrets of the Connector
Key operations fail with a PIN errorThe token rejected the PIN, or has locked itCorrect the secret that the User PIN attribute of the Token references. Unlock a locked PIN on the HSM
Requests fail with a temporary service-unavailable errorThe sidecar or the HSM partition has no free sessionWhen the partition has spare sessions, raise max_sessions within them. Otherwise reduce the load, or free sessions of other clients
A slow operation fails after 35 or 60 seconds, or with a gateway timeoutA timeout on the way of the request expiredOrder the timeouts around the slowest operation, see Timeouts
Utimaco reports a removed device during a slow commandCommandTimeout expired inside the libraryRaise it above the slowest operation and above PKCS11_REQUEST_TIMEOUT, then restart the pod
The Securosys sidecar does not start while the HSM is unreachableconnect_on_init is trueSet it to false in primus.cfg
ppin -t succeeds, but the Securosys profile offers no tokenprimus.cfg names a partition that the enrolled secret does not coverCorrect the partition in primus.cfg
The nShield profile stays downThe HSM is down, does not permit the address of the pod, or the ESN or KNETI hash is wrongRead the log of the sidecar, then check the source address, the ESN and the KNETI hash
The nShield sidecar restarts while the HSM is downThe sidecar has probesRemove its probes
nShield cannot write its key storeThe volume does not admit the group of the sidecarSet an fsGroup that may write the volume
nShield keys disappear when the pod is replacedThe key store is not on a persistent volumeMount a persistent volume at /var/lib/pkcs11-vendor, and restore the key store from its backup
SoftHSM cannot initialize its tokenThe token directory is missing or read-onlyMount a writable volume at /var/lib/pkcs11-vendor/tokens
Two connector pods run during an updateThe Connector resource rolls with the default rolling updateSet strategy.type: Recreate