> ## 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 FXCL application encryption

> Diagnose FXCL connection, authentication, key-store, encryption, Java JNI, and tokenization errors with CryptoHub.

Use the first error signal to identify whether the failure is in the local runtime, TLS connection, authentication context, key-store model, profile binding, or Anchor HSM capability.

## Before you begin

Collect these non-secret facts:

* FXCL package version and OpenSSL family
* Operating system and architecture
* Java version, when applicable
* CryptoHub version
* Native Host API address, port, and expected TLS server name
* Key-store retrievable setting and key usage
* Token-profile client-side setting, algorithm, key store, and active key name

Do not collect API keys, passwords, private keys, clear keys, plaintext, ciphertext, or token values in a support bundle.

## C++ build errors

### Missing OpenSSL version definition

```text theme={null}
Missing OpenSSL version definition. You must define FXCL_OSSL_10, FXCL_OSSL_11, FXCL_OSSL_3 or OPENSSL_VERSION_NUMBER
```

**Cause:** The source includes FXCL OpenSSL-dependent headers, but the build did not select the matching ABI.

**Action:** Add `-DFXCL_OSSL_3` when you use the FXCL OpenSSL 3 package.

### Cannot find libfxcl

```text theme={null}
cannot find -lfxcl
```

**Cause:** The development package is not installed, or the linker does not search the library directory.

**Action:** Confirm `/usr/lib/libfxcl.so` exists and that the linker searches `/usr/lib`.

## Java runtime errors

### UnsatisfiedLinkError

**Cause:** Java found `fxcl-java.jar` but could not load the native FXCL library.

**Action:** Confirm `/usr/lib/libfxcl.so` exists and start Java with:

```bash theme={null}
java -Djava.library.path=/usr/lib \
  -cp .:/usr/share/java/fxcl-java.jar \
  App
```

## TLS and connection errors

### Connection fails before authentication

**Cause:** The application selected the wrong port, CA, server identity, or OpenSSL package family.

**Action:**

1. Confirm CryptoHub publishes the Native Host API on port 2001.
2. Load the CryptoHub production CA, not the web-management CA.
3. Connect with the name in the production certificate.
4. Confirm the FXCL package matches the host OpenSSL family and architecture.

A reachable TCP port without verified TLS is not a successful connection.

## Authentication errors

### USER NOT LOGGED IN

**Cause:** The key or profile operation ran before the Host API login completed.

**Action:** Authenticate with `RKLO`. If the API-key response reports `LN=0`, send a separate `[AORKLO;LN1;]` request on the same connection. Require `AN=Y` and `LN=1` before the operation.

### INVALID PERMISSIONS

**Cause:** The identity's partition does not permit the operation, or the partition does not expose the Excrypt port.

**Action:** Confirm the identity is assigned to the intended non-management partition, the partition permits Excrypt access, and the required Host API commands and key permissions are enabled.

## Key-store errors

### Client-side encryption cannot retrieve a key

**Cause:** The key store is non-retrievable or has no active key.

**Action:** Use `setRetrievable(true)` only for an approved client-side key store. Confirm that key-store creation or rotation produced an active key.

### Remote encryption rejects the store

**Cause:** The remote operation targets a retrievable key, or the key usage does not permit encryption and decryption.

**Action:** Use a non-retrievable `DEK` key store for CryptoHub-backed encryption and confirm `RKED` is enabled.

### Decryption fails after rotation

**Cause:** The application selected only the current active key and lost the identifier for the key that produced the ciphertext.

**Action:** Store the key identifier and cipher context with the ciphertext, or use a DPM header and the matching header-aware decrypt path.

## Tokenization errors

### USER NOT LOGGED IN on TOKA or TOKG

**Cause:** CryptoHub did not accept the deployed identity's token-operation execution context. An identity can manage the key store and profile but still fail a token operation.

**Action:** Authenticate the identity again and run bounded synthetic `TOKA` and `TOKG` operations. Confirm the role and object permissions before you change them. Do not widen a production identity only because key-store or profile management succeeds.

### FAILED TO RETRIEVE ENCRYPTION KEY

**Cause:** The tokenization profile does not have a valid active encryption key, or the key was deleted.

**Action:** Bind both objects before you create the server-side profile:

```java theme={null}
remoteProfile.setKeyStore(remoteStore.getInfo().getName());
remoteProfile.setKey(remoteStore.getKeyInfo().getName());
```

Setting only `keyStore` can create a profile that later fails when `TOKA` or `TOKG` resolves the encryption key.

### FF1 REQUIRES HSM TRUSTED KEYS

**Cause:** The FF1 profile uses a retrievable client-side store.

**Action:** Use a non-retrievable, HSM-trusted key store for server-side FF1. Use the validated FF3-1 path for client-side tokenization.

### INVALID KEY GROUP

**Cause:** The key-store protection model does not match the profile's client-side setting.

**Action:**

* For `clientSide=true`, use a retrievable key store.
* For `clientSide=false`, use a non-retrievable HSM-trusted key store.

### HSM LICENSE MISSING

**Cause:** The profile and active key reached the Anchor HSM, but the Anchor does not have both required FPE features.

**Action:** Enable **Format-Preserving Encryption** and **Format-Preserving Encryption FF1** on the approved Anchor. Do not work around this error by widening application permissions or making the key retrievable.

### Detokenization response is empty

**Cause:** The application reused the `RemoteTokenizeParams` instance that completed tokenization. FXCL updates that object with the selected key.

**Action:** Create a new profile-only `RemoteTokenizeParams` instance for detokenization. Do not pass the key returned by `getKey()` to the detokenization constructor.

### VERIFICATION NOT SUPPORTED

**Cause:** The operation requests token verification, but the profile's verification length is zero.

**Action:** Set a nonzero verification length or disable the verification request.

## Verify the repair

Repeat only the failing bounded operation. Require the operation to advance past its prior failure layer:

* TLS repair: verified connection completes.
* Authentication repair: `RKLO` reports `AN=Y` and `LN=1`.
* Key-store repair: the active key or remote operation resolves successfully.
* Profile repair: the error advances past key retrieval.
* HSM license repair: remote tokenization completes and detokenization recovers the original value.

Clean up all test-owned key stores and profiles after the verification.

## Version and scope

This troubleshooting scope covers FXCL 1.9.5 and CryptoHub 7.2.0.7. Confirm behavior again after an FXCL, CryptoHub, or Anchor firmware upgrade.


## Related topics

- [Troubleshooting](/Integrations/CryptoHub/Code_signing/Java_Jarsigner/Troubleshooting.md)
- [Create an application partition for Futurex PKCS #11](/Integrations/HSM/Generic/Generic_Futurex_PKCS_11/Configure_the_Vectera_Plus/Create_an_application_partition_for_Futurex_PKCS_11.md)
- [Create an application partition](/Integrations/HSM/VPN/OpenVPN_Access_Server/Integration_Steps/Configure_the_Vectera_Plus/Create_an_application_partition.md)
- [Create an application partition for Ansible](/Integrations/HSM/IT_automation_and_orchestration/Ansible/Configure_the_Vectera_Plus/Create_an_application_partition_for_Ansible.md)
- [Create a new identity and associate it with the new application partition](/Integrations/HSM/Generic/Generic_Futurex_PKCS_11/Configure_the_Vectera_Plus/Create_a_new_identity_and_associate_it_with_the_new_application_partition.md)