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

# Troubleshoot Smallstep step-ca

> Resolve observed Smallstep HSM-image, PKCS #11 login, configuration-path, log-permission, and CA key-binding failures.

Match the exact error to the corrective action below. Preserve the first failing application and FxChlibs log lines before changing the configuration.

## `unsupported kms type 'pkcs11': step-ca is compiled without cgo or PKCS11 support`

**Cause:** The standard step-ca package or release binary is running. It cannot load a native PKCS #11 module.

**Fix:** Stop that process and run the pinned HSM image:

```shell title="Shell" theme={null}
sudo docker pull smallstep/step-ca:0.30.2-hsm
sudo docker run --rm \
  --entrypoint /usr/local/bin/step-ca \
  smallstep/step-ca:0.30.2-hsm version
```

The version command reports `Smallstep CA/0.30.2`. Then repeat [Start step-ca](/Integrations/CryptoHub-7.3/Certificate_Authority/Smallstep_step-ca/Start_step-ca).

## `Please enter User PIN` from `pkcs11-tool`

**Cause:** OpenSC initiated `C_Login` before a private-key operation. The Smallstep direct-loader route does not use that login model.

**Fix:** Do not add `--login`, `pin-value`, or `pin-source`. Use `step kms sign` for the Smallstep signing check and keep the endpoint UserPass credential in protected `cryptohub.json`.

```shell title="Shell" theme={null}
source /etc/step-ca/cryptohub.env
export CHLIBS_CONFIG

step kms key \
  --kms "$STEP_KMS_URI" \
  "$STEP_INTERMEDIATE_KEY"
```

The command prints the intermediate public key without prompting for a PIN.

## `error initializing PKCS#11: could not open PKCS#11`

**Cause:** Smallstep cannot load the module or its endpoint configuration. A missing `CHLIBS_CONFIG` produces this error before key access.

**Fix:** Verify the environment, module, configuration, and referenced TLS files:

```shell title="Shell" theme={null}
source /etc/step-ca/cryptohub.env
export CHLIBS_CONFIG

test -r "$CHLIBS_CONFIG"
test -x "$FUTUREX_DIR/libcryptohub-pkcs11.so"
ldd "$FUTUREX_DIR/libcryptohub-pkcs11.so" | grep 'not found' && exit 1 || true

sudo jq -e '
  .cryptohubs[0].tls.verify == true and
  .authentication.users[0].username != "" and
  .authentication.users[0].password != ""
' "$CHLIBS_CONFIG" >/dev/null
```

All commands exit with status 0 when the module and endpoint configuration are available. For a container failure, also confirm that `/opt/futurex` is mounted at the same path inside the container.

## `Log file ... is not writable; using temporary log file`

**Cause:** A host process created the log without group-write permission before the container started.

**Fix:** Restore the runtime group and file mode, then restart the container:

```shell title="Shell" theme={null}
sudo chown root:step-ca /var/log/futurex/smallstep-chlibs.log
sudo chmod 0660 /var/log/futurex/smallstep-chlibs.log
sudo docker restart stepca
```

Run another certificate issuance. The host log now gains new `C_SignInit` and `C_SignFinal` entries.

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

**Cause:** `ca.json` references one CryptoHub key while `intermediate_ca.crt` contains a different public key. This often occurs when the software intermediate from `step ca init` remains in place.

**Fix:** Reissue the intermediate certificate with the exact `STEP_INTERMEDIATE_KEY`, then compare both public keys before replacing the certificate. Follow [Configure step-ca to use CryptoHub](/Integrations/CryptoHub-7.3/Certificate_Authority/Smallstep_step-ca/Configure_step-ca_to_use_CryptoHub).

Do not delete or replace the CryptoHub key until the public-key comparison and root-chain verification pass.

## The container reports a missing path under `/home/step/.step`

**Cause:** `ca.json` still contains host paths such as `/var/lib/smallstep/.step/db`. Those paths do not exist in the container.

**Fix:** Set `root`, `crt`, and `db.dataSource` to their `/home/step/.step/` paths, then restart:

```shell title="Shell" theme={null}
jq '{root, crt, address, db: .db.dataSource}' \
  /var/lib/smallstep/.step/config/ca.json
sudo docker restart stepca
```

The output must show container paths for both certificates and the database. The health endpoint returns `{"status":"ok"}` after the restart.