CKR_OBJECT_HANDLE_INVALID
Object handles are per-session and they are ordinary integers, which is a combination that hides mistakes well. A search that matched nothing, a handle kept past the session that produced it, and a handle borrowed from another session all look identical at the call site, and all of them arrive here. Zero is a particularly common value to pass by accident.
What the token is reporting
The library does not recognise the object handle in this session. Either it never issued that handle here, or the object it referred to has been destroyed since.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 search found nothing and nobody checked
A find that matches no object is not an error. It returns successfully with a count of zero, and code that reads the first element of the result array without checking the count passes whatever was in that memory, often zero, into the next call.Check it: Check the count the find returned rather than the return code. A successful search with nothing in it is the normal way this happens.
A private object, and the session is not authenticated
Private objects are invisible rather than forbidden before login, so the search succeeds and finds nothing at all. The failure then appears one call later as a bad handle, which points nowhere near the actual cause.Check it: Repeat the search after logging in. If the object appears, the handle was never the problem.
The handle came from a different session
Handles are scoped to the session that produced them. A connection pool that hands out sessions while caching handles alongside them will eventually pair the two incorrectly.Check it: Trace the session the handle was found in and the session it was used in. If they differ, that is the answer regardless of what else is happening.
The object was destroyed, or the token restarted
Session objects vanish when their session closes, and any object goes away when something destroys it. Another process cleaning up shared token objects will invalidate handles you are holding.Check it: Search for the object again by label. If it is gone, the question is who removed it, not why the handle failed.
Which calls return it
C_GetAttributeValue, C_SignInit, C_DestroyObject, C_WrapKey
What it is not
It is not a permissions error. A token does not refuse an object it can see, it simply does not show you objects you may not have, which is why this so often turns out to be an authentication problem wearing a different code.Often confused with
CKR_SESSION_HANDLE_INVALID: The same mistake one level up. If the session handle is also stale, fix that first, because the object handles behind it cannot be valid either.CKR_USER_NOT_LOGGED_IN: The underlying cause in a large share of cases, showing up one call later than it should.
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.