> ## Documentation Index
> Fetch the complete documentation index at: https://docs.futurex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose and resolve the common failure modes of the Smallstep step-ca and CryptoHub integration.

Each entry below names the error string you see, then the cause and the fix.

## `unsupported kms type 'pkcs11': compiled without cgo or PKCS#11 support`

**Symptom:** `step-ca` exits at startup with this message as soon as it reads the `kms` block in `ca.json`.

**Cause:** You are running the `step-ca` binary from the official package or release archive. Those builds are compiled without PKCS #11 support and cannot load any PKCS #11 module.

**Solution:** Run the CA from the `smallstep/step-ca:hsm` container image instead, as described in [Start step-ca](/Integrations/CryptoHub/Certificate_Authority/Smallstep_step-ca/Start_step-ca). Keep the host `step-ca` package installed for the toolchain, but do not use it to serve the CA.

## The container exits immediately after docker run

**Symptom:** `sudo docker ps` shows no running container, and `sudo docker logs stepca` reports that a file or directory does not exist, naming a path under your host home directory such as `/home/<user>/.step/certs/root_ca.crt` or `/home/<user>/.step/db`.

**Cause:** `step ca init` writes host-absolute paths into `ca.json`. The container mounts `~/.step` at `/home/step/.step`, so those host paths do not exist inside it.

**Solution:** Rewrite the `root`, `crt`, and `db.dataSource` values in `ca.json` to their `/home/step/.step/...` equivalents:

```shell expandable lines wrap title="Shell" theme={null}
sed -i "s|$HOME/.step|/home/step/.step|g" ~/.step/config/ca.json
```

Leave the `kms` block's `module-path` unchanged, because the FXPKCS11 directory is mounted at the same absolute path in both runtimes. Then confirm two other container requirements are in place: `--entrypoint step-ca`, so the image's startup script does not swallow your arguments, and `--password-file`, so a detached container is not left waiting for a password prompt it cannot receive.

## CKR\_TEMPLATE\_INCONSISTENT from step kms create

**Symptom:** `step kms create --kty RSA --size 3072` fails with `CKR_TEMPLATE_INCONSISTENT`.

**Cause:** The key template the step-kms-plugin sets is rejected by FXPKCS11 `5.23`. This is a limitation of that command against this module, not a configuration error.

**Solution:** Generate the key with `PKCS11Manager` or `pkcs11-tool --keypairgen`, as described in [Generate a CA signing key](/Integrations/CryptoHub/Certificate_Authority/Smallstep_step-ca/Generate_a_CA_signing_key). Every later `step kms`, `step certificate`, and step-ca operation works normally against a key created that way.

## A step kms or step certificate command cannot find the key

**Symptom:** `step kms key`, `step kms sign`, or `step certificate create` reports that it cannot find the key, even though `pkcs11-tool --list-objects` shows `smallstep-ca-key`.

**Cause:** The PKCS #11 URI names the object but not its ID. FXPKCS11 needs both to resolve the key.

**Solution:** Use the full URI in every command and in both `ca.json` references:

```text expandable lines wrap title="Text" theme={null}
pkcs11:id=7101;object=smallstep-ca-key
```

Substitute your own ID if you chose a value other than `7101` during key generation, and use the same value everywhere.

## x509: provided PrivateKey doesn't match parent's PublicKey

**Symptom:** step-ca exits at startup with this message.

**Cause:** The intermediate CA certificate at `~/.step/certs/intermediate_ca.crt` does not correspond to the key that `ca.json` references. This happens when the software intermediate certificate from `step ca init` is still in place, or when the CryptoHub key was regenerated after the intermediate was issued.

**Solution:** Reissue the intermediate certificate against the CryptoHub-resident key and copy it into place, as described in [Configure step-ca to use CryptoHub](/Integrations/CryptoHub/Certificate_Authority/Smallstep_step-ca/Configure_step-ca_to_use_CryptoHub). The certificate on disk and the key in `ca.json` must always be the same key pair.

## `could not find PKCS#11 token`

**Symptom:** step-ca or a `step kms` command reports that it cannot find the token. The module loaded, but it could not reach the CryptoHub.

**Cause:** One of the module's inputs is missing or unresolvable, most often a configuration path, a TLS file path, or the PKCS #12 password.

**Solution:** Check the following in order:

1. `FXPKCS11_CFG` points at `/usr/local/lib/fxpkcs11/fxpkcs11.cfg`. For the container, confirm the `-e FXPKCS11_CFG=...` flag is present in the run command.
2. `PROD-TLS-KEY` and both `PROD-TLS-CA` values in `fxpkcs11.cfg` are absolute paths under `/usr/local/lib/fxpkcs11` and match the file names present there. Relative names resolve against the working directory, which differs between your shell and the container.
3. `PKCS11_P12` holds the PKCS #12 password. Run `echo "$PKCS11_P12"` in the shell you use. An empty value passes through `-e PKCS11_P12="$PKCS11_P12"` silently.
4. The step-ca host can reach the CryptoHub address and port 2001 named in `fxpkcs11.cfg`.

Read the FXPKCS11 log for the specific failure. Its location comes from the `LOG-FILE` setting in `fxpkcs11.cfg`, and the module falls back to `/tmp/fxpkcs11.log` when it cannot write there:

```shell expandable lines wrap title="Shell" theme={null}
sudo docker exec stepca cat /tmp/fxpkcs11.log
```

## step kms sign rejects the --digest flag

**Symptom:** `step kms sign` reports an unknown flag for `--digest`, or rejects a hexadecimal digest passed as a positional argument.

**Cause:** step-kms-plugin `0.15.1` signs a file rather than a precomputed digest.

**Solution:** Pass the input file with `--in` and the digest algorithm with `--alg`:

```shell expandable lines wrap title="Shell" theme={null}
step kms sign --kms 'pkcs11:module-path=/usr/local/lib/fxpkcs11/libfxpkcs11.so;token=Futurex?pin-value=<PIN>' --in /tmp/test.txt --alg SHA256 'pkcs11:id=7101;object=smallstep-ca-key' > /tmp/test.sig
```

## step kms sign --verify prints nothing

**Symptom:** `step kms sign --verify` produces signature output but no confirmation that the signature is valid.

**Cause:** The flag reports its result through the process exit code, where `0` means valid. It prints no status word.

**Solution:** Read the exit code, or verify independently with OpenSSL, which prints a visible result:

```shell expandable lines wrap title="Shell" theme={null}
openssl dgst -sha256 -verify /tmp/smallstep-ca.pub -signature /tmp/test.sig /tmp/test.txt
```

## configTest reports permission denied

**Symptom:** Running `configTest` or `PKCS11Manager` returns `Permission denied`.

**Cause:** The test utilities are not executable after the endpoint ZIP is extracted.

**Solution:** Add the execute bit:

```shell expandable lines wrap title="Shell" theme={null}
sudo chmod +x /usr/local/lib/fxpkcs11/configTest /usr/local/lib/fxpkcs11/PKCS11Manager
```