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

> Guidance for diagnosing and resolving runtime errors when OpenSSL and Java share the same PKCS#11 library.

## Runtime Errors

### Symptom: Java hangs after installing and configuring SunPKCS11 with FxPKCS11

If Java and OpenSSL are pointing to the same `libfxpkcs11.so`, you might run into an issue where running a Java HSM-specific command will cause a hang.
Error logs will look similar to:

```none expandable lines wrap title="None" theme={null}
[2025-12-03 17:05:58.378] | DEBUG | 73FE95AFF6C0 | waitForConnect: Blocking for up to 3000 milliseconds on socket connect.
[2025-12-03 17:05:58.379] | INFO  | 73FE95AFF6C0 | establishConnectionIP: Socket 6 connects to 10.0.5.111:9100.
[2025-12-03 17:05:58.379] | INFO  | 73FE95AFF6C0 | setupSSL: Setting up SSL. (Slot 0)
[2025-12-03 17:05:58.645] | DEBUG | 73FF0EDFF6C0 | C_Initialize: Blocking until surveyor has completed its initial HSM check (10s Max).
[2025-12-03 17:06:09.302] |*ERROR*| 73FF0EDFF6C0 | C_Initialize: Surveyor failed to complete its initial HSM check within the timeout.
[2025-12-03 17:06:09.302] | INFO  | 73FF0EDFF6C0 | C_Initialize: FxPKCS11 library initialized.
[2025-12-03 17:06:09.302] | INFO  | 73FF0EDFF6C0 | C_Initialize: FxPKCS11 library version 5.15 (Revision: 4fee).
[2025-12-03 17:06:09.302] | INFO  | 73FF0EDFF6C0 | C_Initialize: Platform: Linux
```

#### Solution

Make sure that Java points to a different `libfxpkcs11.so` by editing the `pkcs11.cfg` file.

<Steps>
  <Step>
    Create a new directory. We would recommend a directory with a path similar to: `/usr/local/lib/fxpkcs11/java`
  </Step>

  <Step>
    Copy the `libfxpkcs11.so` file to the newly created directory
  </Step>

  <Step>
    Edit the `pkcs11.cfg` file. If the user followed the guide, the file would be found in `/usr/local/etc`
  </Step>

  <Step>
    Edit the `library` line so that it will point to copied `libfxpkcs11.so`

    ```none expandable lines wrap title="None" theme={null}
    name = Futurex
    library = /usr/local/lib/fxpkcs11/java/libfxpkcs11.so
    slotListIndex = 0
    ```
  </Step>

  <Step>
    Retest Java command to make sure that it is now able to succeed
  </Step>
</Steps>

#### Verification

To retest, youi can run a basic HSM + Java command

```shell expandable lines wrap title="Shell" theme={null}
keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerName SunPKCS11-Futurex 
```

A successful output should look like:

```none expandable lines wrap title="None" theme={null}
Keystore type: PKCS11
Keystore provider: SunPKCS11-Futurex

Your keystore contains 0 entries
```