Exceptions
Below is the list of messages that can accompany a TokenException, along with some troubleshooting tips for each scenario. The list of tips is by no means exhaustive.
In situations when the TokenException was caused by an underlying SQLException, that message is displayed in the exception.
| Exception Message | Explanation and/or troubleshooting tips |
|---|---|
| For Java17, if following exception is thrown: java.lang.reflect.InaccessibleObjectException: Unable to make field private static volatile java.net.Authenticator java.net.Authenticator.theAuthenticator accessible: module java.base does not "opens java.net" to unnamed module. | Add --add-opens java.base/java.net=ALL-UNNAMED command to the Tomcat configuration. |
| Alpha characters are not allowed when using the Luhn check | To use the Luhn check, the input data must contain only numeric values. Review your input data to be sure that only numeric values exist. |
| calendarDate is missing | Your application did not pass a calendarDate parameter when calling getTokensByDate(). Review that section of your code. |
| Cannot create connection pool | Could not create a connection pool using your db username and password. Verify that the values in your properties file and/or the method call are correct. Also confirm that your database connection is working properly. |
| Cannot decrypt the value: <text from underlying exception> | Verify that you are using the correct key name and token vault. Check the key’s status on the Key Manager. |
| Cannot get the token | If the token uses the sequence format, the sequence could not be created in the database. Verify your database settings. Confirm that the database can create sequential values. |
| CreateNewFormat: (leadPositions + trailPositions) cannot be more than token length | When creating a new token format, the lead and trail position values cannot be larger than the token length. Check the leadPositions, trailPositions, and tokenLength parameters passed to createNewFormat(). Remember that the smaller the difference between leadPositions + trailPositions and tokenLength, the less room there is for the CT-V to generate a token value. |
| CreateNewFormat: Lead and Trail positions values cannot be negative | Your new token format includes negative values for the lead and/or trail positions. Remove the negative values. |
| CreateNewFormat: luhnCheck valid values are -1, 0, 1. | Use a valid value for luhnCheck. |
| CreateNewFormat: The length of leadMask cannot be equal to token length when luhnCheck is -1 or 1 | When creating a new token format, the leadMask value cannot be equal to the tokenLength when luhnCheck is -1 or 1. Check the leadMask and tokenLength parameters passed to createNewFormat(). Remember that the smaller the difference between leadMask and tokenLength, the less room there is for the CT-V to generate a token value. |
| CreateNewFormat: The length of leadMask cannot be more than token length | When creating a new token format, the leadMask value cannot be larger than the tokenLength. Check the leadMask and tokenLength parameters passed to createNewFormat(). Remember that the smaller the difference between leadMask and tokenLength, the less room there is for the CT-V to generate a token value. |
| CreateNewFormat: Token cannot be longer than 256 characters | A token cannot be larger than 256 characters. Check your application’s call to createNewFormat(). tokenLength must be 256 or less. |
| CreateNewFormat: Token length cannot be negative | tokenLength cannot be a negative number. Check your application’s call to createNewFormat(). |
| Crypto error in deleteValue(): <text from underlying exception> | An XMLException, IOException, or GeneralSecurityException was thrown when trying to delete a value from the token vault. The TokenException includes the message from the underlying exception. Review that text for more information. |
| Crypto error in getToken(): <text from underlying exception> | An XMLException, IOException, or GeneralSecurityException was thrown when trying to delete a value from the token vault. The TokenException includes the message from the underlying exception. Review that text for more information. |
| Crypto error in insert(): <text from underlying exception> | A GeneralSecurityException was thrown when trying to encrypt or mac the plaintext value. The TokenException includes the message from the underlying GeneralSecurityException. Review that text for more information. |
| Custom data for element <value> exceeds the maximum custom data length of <max length> | The custom data included in this method call exceeds the maximum length. Review the call to getToken(), insert(), get(), or deleteValue(). The maximum length for the custom data field is included in the exception and error messages. |
| Database error in getKeyName(): <text from underlying exception> | Check that the key exists in the key table and that you’ve used the correct token vault name. Verify that the database connection is working properly. |
| Database error in insert: <text from underlying exception> | A SQLException was thrown when trying to register the database driver, access the database or close the connection. Confirm that the database-related parameters in the SafeNetToken.properties file are correct. Confirm that the database connection is working properly. |
| Database error: <text from underlying exception> | A SQLException was thrown when trying to register the database driver, access the database or close the connection. Confirm that the database-related parameters in the SafeNetToken.properties file are correct. Confirm that the database connection is working properly. Verify that the database user has the privileges needed to set the tablespace, and SELECT, UPDATE, and INSERT INTO the token vault and sfnt_key_table. |
| Database login info is missing. | The database username and/or password is missing. Verify that the username and password are present while creating TokenService instance. |
| Encryption key is not set for table | There is no key associated with your token vault. Verify that you are using the correct token vault name and that the token vault was properly configured. |
| Encryption key must be versioned | You’ve selected an un-versioned key for the token vault. You can only use versioned AES-256 keys for encryption. |
| getToken: Input value cannot be null | Your application has passed a null for the value parameter in the call to getToken(). Check your code. value must be a non-null, plaintext value. |
| HMAC key cannot be versioned. | You’ve selected a versioned HMAC key. You can only use un-versioned HMAC keys. |
| HMAC key is not set for table. | There is no HMAC key associated with your token vault. Verify that you are using the correct token vault name and that the token vault was properly configured. |
| Illegal characters in the data. | The plaintext contains illegal characters. The plaintext value can have digits, whitespace, and dashes only. It cannot be null or blank. The first and last characters must be digits. |
| Illegal characters in the input data. | The plaintext contains illegal characters. The plaintext value can have digits, whitespace, and dashes only. It cannot be null or blank. The first and last characters must be digits. |
| Illegal characters in the leadMask: Only digits are allowed. | The leadMask contains illegal characters. The leadMask can have digits only. |
| Illegal characters in the token. | The token contains illegal characters. The token value can have digits, whitespace, and dashes only. |
| Input data for element <value> exceeds the maximum cleartext length of <length> | The input data included in this method call exceeds the maximum length. Review the call to getToken(), insert(), or mask(). The maximum cleartext length is included in the exception and error messages. |
| Input data length is invalid integer | The input data length must be a positive integer. |
| Input data length should be positive | The input data length must be a positive integer. |
| Input data length should be provided | To create sequential tokens, you must set the input value length. |
| Input data must have at least <number> digits when applying a Luhn check | To apply a Luhn check, the input data must have at least 10 digits. Review your input data to be sure that it conforms with this setting. |
| Input value cannot be null | Your application’s call to getToken() includes a null as the input value. Review your code and your input data. |
| Input value is too short for specified format | The input value must be appropriate for the token format. Check that the input value is correct for the token format. For user-defined token formats: check that the mask length is correct for the format; check that the leadPositions and trailPositions are correct for the format. |
| Input values cannot be empty | Your application has included a null in the values array in the call to mask(). Check your code. The values array cannot contain null values. |
| Input values cannot be null | Your application has passed a null for the values parameter in the call to getToken(). Check your code. value must be a non-null, plaintext value. |
| Insert values cannot be empty | The plaintext value you’ve passed in insert() is empty. |
| insert() does not support the mask format. | You cannot use the MASK_TOKEN format when creating a token. Check the list of available token formats in the documentation. Review your use of insert(). |
| Invalid connection object | There was a problem releasing the connection to the token vault. Check the connectivity with your database. |
| Invalid date format value: <format> | Your application is passing an invalid date format to either insert() or mask(). Check the list of available token formats in the documentation. Review your use of insert() and mask(). |
| Invalid date length | A date with a length of 8 was passed when a length of 10 is required. The two separator characters are required. The expected format is DD/MM/YYYY, MM/ DD/YYYY, or YYYY/DD/MM, based on the token format where '/' can be any valid separator. |
| Invalid format | The call to insert() or get() uses an invalid token format. |
| Invalid format value | Your application is passing an invalid format to either insert() or mask(). Check the list of available token formats in the documentation. Review your use of insert() and mask(). |
| Invalid luhn check value | The call to insert() or mask() includes an invalid luhn check value. The luhnCheck parameter is a boolean. |
| invalid or missing <parameter> property in SafeNetToken.properties | The parameter could not be found in the properties file. Verify that the parameter exists in the SafeNetToken.properties file. Recreate it if needed. |
| Invalid port in SafeNetToken.properties | The port number must be an integer between 0 and 65535. Verify the Port parameter in the SafeNetToken.properties file. |
| Invalid token. | The call to get() uses a null, or otherwise invalid value for the token. |
| Key rotation is currently active for table | The table you are attempting to rotate is in the middle of a key rotation process. Wait for the previous rotation to end before starting the new process. |
| Luhn check is not supported for sequential tokens. | There can be no Luhn check for sequential tokens. When creating sequential tokens, the luhnCheck parameter should be false. |
| Luhn check is not valid when using the format value <format> | Luhn checks cannot be applied when the token format is SEQUENTIAL_TOKEN, EMAIL_ADDRESS_TOKEN, FIXED_FIRST_TWO_LAST_FOUR_FAIL_LUHN_TOKEN, FIRST_SIX_LAST_FOUR_FAIL_LUHN_TOKEN, or any of the date formats. Review your call to insert() or mask(). |
| MASK is not a valid format for insert operation. | You cannot use the MASK_TOKEN format when creating a token. Check the list of available token formats in the documentation. |
| NAE login info is missing. | The username and/or password needed to connect to the Key Manager is missing. |
| No tokens passed in. | The call to get() or the call to deleteToken() uses a null value. You must use a real token value. |
| No values are passed in. | The plaintext values are missing. You need plaintext values to create tokens. |
| No values passed in. | The call to deleteValue() is either null, or contains no values. |
| One or both provided keys are invalid; or connection setup is wrong. <text from underlying exception> | Check the nae username and password you provided. Also check the key permissions. |
| Property File can’t be loaded | The property file was found but could not be loaded. |
| PropertyVetoException caught: <text from underlying exception> | Could not load the jdbc driver. Check your database connection. |
| Read timed out | A read time out can occur when sending batch requests to a token vault in an Oracle database. This can be avoided by executing the analyze table command after running the first batch job:analyze table <your token vault> compute statistics;If this command is not used, performance will degrade after running batches between 5000 and 10000 rows. |
| System property com.safenet.token <parameter> is not set and com.safenet.SafeNetToken_Properties_Conf_Filename file is not found | The parameter could not be found in the properties file and/or the SafeNetToken.properties file couldn’t be found. Put the properties file in the default location (JAVA_HOME/lib/ext) or set your CLASSPATH accordingly. The IngrianNAE.properties file must be in the same directory as the IngrianNAE-8.12.2.000.jar file. The SafeNetToken.properties file must be in the same directory as the SafeNetTokenService-8.12.4.000.jar file. |
| Table name is missing. | The token vault name is missing. Verify that the method or command includes a value for the token vault name. |
| The length for FIXED_TWENTY_LAST_FOUR_TOKEN must be at least 10 digits | When using the FIXED_TWENTY_LAST_FOUR_TOKEN, the input data must be at least ten digits long. Review your input data. |
| The tokens and customData arrays must have the same number of elements. | The tokens and customData arrays do not have the same number of elements. Review your application’s call to get(). |
| The values and customData arrays must have the same number of elements | The values and customData arrays do not have the same number of elements. Review your application’s call to getToken(), insert(), and/or deleteValues(). |
| Token and cleartext should be the same length. | Plaintext and the token must be the same length. |
| Token cannot be null. | The call to get() or deleteToken() uses a null value for the token. It must contain an actual token. |
| Token length should be the same as the decrypted value. | Token length and plaintext length must be the same for the selected token format. |
| Token length should be the same as the input value. | Except when using the FIXED_NINETEEN_TOKEN format, the input data length must match the token length. |
| TokenService cannot get DB connection: <text from underlying exception> | Verify that the values in your SafeNetToken.properties file and/or the method call are correct. Also confirm that your database connection is working properly. |
| TokenService cannot get NAE connection: <text from underlying exception> | Verify that the values in your IngrianNAE.properties files and/or the method call are correct. |
| Unable to get an instance of the random number generator: <text from underlying exception> | The CT-V could not get an instance of the random number generator used to create random dates. Review the exception for more details. |
| Unable to tokenize the value -- no space for tokens. | Given the combination of token format and input value, there is not enough data to tokenize. Review the length of the input data and the token format you’ve selected. If you are using a format created by calling createNewFormat(), be sure that the combination of leadPositions, trailPositions, leadMask, and luhnCheck leave space for the token values. |
| Unable to tokenize this value | The input value could not be tokenized using the format you requested. Review your call to insert() or mask(). Be sure that the token format selected can be properly applied to the input data. If you are using a format created using createNewFormat(), be sure that the combination of leadMask, leadPositions, trailPositions, and luhnCheck leave enough characters for the CT-V to manipulate. |
| Unknown date format | Your application is passing an invalid date format to either insert() or mask(). Check the list of available token formats in the documentation. Review your use of insert() and mask(). |
| Value cannot be null. | The plaintext value cannot be null. Verify the plaintext value included in your call to getToken() or deleteValue(). |
| Values cannot be null | Plaintext values cannot be null. Verify the plaintext values included in your call to getToken(). |
| Function has none of DETERMINISTIC, NO SQL, or READS SQL DATA in its declaration and binary logging is enabled | Token vault creation failure in MySQL. Execute the following in MySQL database:SET GLOBAL log_bin_trust_function_creators = 1 |
| Execute command denied to user <dbuser>@<Ipaddress> for routine <dbName>.TMF_<VaultName> | As a workaround to this issue, execute the following command in MySQL database:GRANT EXECUTE ON FUNCTION <dbName>.TMF_<VaultName> TO <dbuser>@<Ipaddress> |
| code-set conversion function failed due to illegal sequence or invalid value | When this error is encountered in Java APIs insert() or get() for Informix database, add _JdbcUrlOverride in SafeNetToken.properties file as given in the following syntax: _JdbcUrlOverride=jdbc:informix-sqli://<hostname>:<port>/<databasename>:INFORMIXSERVER=<server_name>;NEWCODESET=8859_1,8859-1,819 |
| Could not load file or assembly 'TokenServiceJNI.dll' or one of its dependencies. The specified module could not be found. | This error may be observed while using IIS web services in Java 10. Possible cause can be due to multiple CADP JCE Provider jars in any other Java versions installed on the machine. Workaround: Delete the additional CADP JCE Provider jars apart from the location where the CADP JCE Provider is installed for Java 10. |
