> ## 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 common failures when connecting Nexus PKI and the hwsetup tool to CryptoHub.

Each entry below describes a symptom, then the cause and the fix.

## hwsetup fails to log in when you run it from PowerShell

**Symptom:** `hwsetup.bat` reports a login failure or a malformed command when you run it from PowerShell, but the same PIN works in `PKCS11Manager.exe`.

**Cause:** The PKCS #11 PIN contains `&`. PowerShell does not pass the character to a batch file intact, so `hwsetup` receives a truncated PIN or a split command.

**Solution:** Run `hwsetup.bat` from Command Prompt (`cmd.exe`) and wrap the PIN in double quotes:

```shell expandable lines wrap title="Command Prompt" theme={null}
hwsetup.bat -libname "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.dll" -slot 0 -pin "YOUR_PIN"
```

## hwsetup cannot load the PKCS #11 library

**Symptom:** `hwsetup` reports that it cannot load the library or the native bridge before it reaches the CryptoHub.

**Cause:** One of the two native libraries is missing or mismatched. `hwsetup` loads the 64-bit Nexus bridge `jpkcs11.dll` from the `bin` directory of the tool package, and the bridge then loads `fxpkcs11.dll`.

**Solution:** Check the following:

1. The tool package keeps its `bin`, `lib`, and `tools` structure, and you run `hwsetup.bat` from the `tools` directory.
2. `jpkcs11.dll` is the 64-bit build, and Java is the 64-bit Java 21.
3. The `-libname` value is the full path to `fxpkcs11.dll`, in double quotes because the path contains spaces.

## hwsetup or configTest cannot connect to CryptoHub

**Symptom:** `configTest.exe` fails, or `hwsetup` loads the library but reports no token in slot `0`.

**Cause:** The module cannot complete the mutual TLS session to the CryptoHub Host API.

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

1. `fxpkcs11.cfg` is in `C:\Program Files\Futurex\fxpkcs11`, or **FXPKCS11\_CFG** points at it.
2. `client.p12` and the `.cer` files are in the same directory as `fxpkcs11.cfg`.
3. `PKCS11_P12` holds the PKCS #12 password. Open a new Command Prompt and run `echo %PKCS11_P12%`. A variable set with `setx` is visible only to processes started afterward.
4. The host can reach the CryptoHub hostname in `fxpkcs11.cfg` on TCP port 2001, and no TLS inspection proxy sits in the path.

Read the FXPKCS11 log in `C:\Program Files\Futurex\fxpkcs11` for the specific failure.

## The key does not appear in Existing key ID

**Symptom:** In the AWB **Create Key Request** dialog, the **Existing key ID** list does not include the key you generated.

**Cause:** The list shows only keys that are not already in use, on the device you selected. The key is already assigned to another CA key, or the CIS device points at a different slot or service.

**Solution:** Run `hwsetup -list` with the same library, slot, and PIN that the CIS device uses, and confirm the key ID appears. If it does not, the CIS device and `hwsetup` are using different endpoint configurations or PINs. If the key ID appears but is already in use, generate a new key pair with a new ID.

## Certificate Manager starts in maintenance mode

**Symptom:** After you add the CryptoHub device, Certificate Manager starts in maintenance mode.

**Cause:** The CIS configuration file changed but was not signed.

**Solution:** Sign the CIS configuration file with an officer that holds the **Configuration tasks** role, then restart Certificate Manager. Refer to [Sign CF and CIS configuration files in Certificate Manager](https://doc.nexusgroup.com/nexus-certificate-manager/8.15/sign-cf-and-cis-configuration-files-in-certificate-manager).