CKR_GENERAL_ERROR: the one you cannot retry

Of all the vague codes in this specification, this is the one with teeth. It does not mean the call failed. It means the library or the token has reached a state where nothing else is expected to work either, so the correct response is to tear down and start again rather than to try something slightly different. Code that treats it as an ordinary failure tends to spend a long time failing.

What the token is reporting

Something went wrong at a level the library cannot describe or recover from. The specification is unusually direct about the consequence: once you have seen it, further calls are not expected to succeed, and the library should be finalized and re-initialized before anything else is attempted.

Likely causes

Ordered by how often they turn out to be the answer. That ordering is a judgement from experience, not a measured frequency.

The library cannot find or read its configuration

Most vendor libraries read a configuration file to find the token, and a missing file, a path pointing somewhere else, or a file the process cannot read produces a failure long before any cryptography happens. The library has nothing sensible to report, so it reports this.

Check it: Run the vendor’s own status tool as the same user, from the same environment, as the failing process. If the tool works and your process does not, the difference is in the environment rather than in your code, and the configuration path variable is the first thing to compare.

Wrong library, or an architecture mismatch

Loading a library built for a different token, or a 32-bit module into a 64-bit process, fails in ways that have no clean error. This is especially easy on machines where more than one vendor’s software is installed, because the file names are similar and the paths are long.

Check it: Check the file you actually loaded rather than the one you meant to. Confirm its architecture matches the process, and confirm the path belongs to the vendor whose token you expect.

The token entered an error state

A failed self test, a tamper event or a firmware fault can put the device into a state where it will answer nothing. The library passes that along as the most severe code it has.

Check it: Read the device’s own event log. A tamper or self test failure is recorded there, and no amount of work on the client side will change it.

An internal fault in the library

Sometimes it really is a bug, and there is nothing on the calling side to fix. That is worth considering only after configuration, path and device state have been ruled out, because it is the least likely and the most tempting explanation.

Check it: Reproduce with the vendor’s own sample tool. If the vendor’s tool fails the same way, you have something to send them.

Which calls return it

C_Initialize, C_GetSlotList, C_OpenSession, C_Login

What it is not

It is not a transient condition, and it is not an argument problem. A retry loop around it will not recover, and re-reading your template will not help, because by the time you see it the library has already given up on the whole session rather than on the one call.

Often confused with

CKR_FUNCTION_FAILED: The pair worth learning. That one means this call failed and the library is still usable. This one means stop.

By library

SoftHSMv2

This is SoftHSMv2’s everyday failure code, not its emergency one. return CKR_GENERAL_ERROR appears 206 times in [SoftHSM.cpp](https:// github.com/softhsm/SoftHSMv2/blob/884cb38f3d2012a0447bd5f50dbd29c42998 7c41/src/lib/SoftHSM.cpp), covering a crypto backend that refused an operation, a session whose token has gone, and two functions where an unauthenticated read of a private object is deliberately reported this way instead of as a login problem. The library is fine afterwards. Tear-down is the wrong response here, and the right one is to raise the log level and read the line above.

OpenSC

On OpenSC this is the default of the translation switch in [misc.c](ht tps://github.com/OpenSC/OpenSC/blob/4fab8b57301f035432191d582922d95d7d 426802/src/pkcs11/misc.c#L70-L123). About twenty-five card errors have a PKCS#11 equivalent. The other sixty or so, out of the 84 libopensc defines, fall through to the general error. The card’s real reason is one line up in the OpenSC debug log, and nothing about the library’s state can be inferred from the code alone.

Thales ProtectServer

The ProtectToolkit 7.3 hardware library, libcthsm.so, returns this from C_Initialize itself when no HSM is reachable, which I saw on a machine with the SDK installed and no device. That is the code used as the specification intends, the library cannot be used, and the fix is the device or the transport to it rather than anything in the application. The software-only library initialises without one.

Sources

PKCS #11 Specification Version 3.2, OASIS. Read 2026-09-10. Used for constant name and numeric value.

Every description, cause and check on this page is written from scratch. The specification is cited for the constant's name and its number, which are facts, and for nothing else.