Troubleshooting.

Start with the connection, then the session, then the operation.

The host cannot find the stick

Check the USB connection and that the expected firmware is running. On Linux, lsusb can show whether the ESP USB device enumerated. Current development transport IDs are 303a:1001.

These IDs are shared with other ESP devices. Disconnect other matching development boards when diagnosing a multiple-devices error. The Rust library intentionally fails when several candidates match.

USB access or interface errors

Enumeration does not guarantee permission to claim the USB interface. Check your system’s USB access rules and whether another program has claimed the interface. Running an application as root should not be the normal setup.

The host expects configuration 1, data interface 1, alternate setting 0, and bulk endpoints 0x01/0x81. A descriptor mismatch may mean a different firmware or a different ESP device.

The library claims the USB interface directly rather than opening a serial port. Kernel-driver detach and reattach behavior can affect whether a /dev/ttyACM* node is visible.

Authentication-required or invalid state

Check both token and session state. An uninitialized token cannot be fixed by repeatedly authenticating; it needs provisioning through the development workflow. The current public host APIs do not yet expose initialization.

A ready token can still have a closed session. Authenticate before a protected operation, and handle session expiry between a status query and a request. Calling authenticate or lock in the wrong session state can fail.

Missing keys or unexpected label matches

List key metadata and confirm type, usage, and ID. Labels are not unique. Seal requires exactly one key with the requested label; use distinct labels for Seal and Keyring keys.

A replacement key with the same label does not decrypt data from the original key. IDs can also be reused after deletion.

A long operation times out

RSA key generation may exceed the Rust host library’s current fixed 10-second timeout, especially RSA-4096. The key could still have been created even if the host did not receive a response.

Restore a usable connection and inspect device state before trying again. Do not repeatedly generate, derive, delete, or initialize after a timeout without resolving the previous outcome.

Interoperability or format failures

Public keys use DER SubjectPublicKeyInfo, not a raw EC point or PKCS#1 RSA encoding.
Device RSA decryption uses OAEP/SHA-1, not OAEP/SHA-256.
ECDH requires a matching peer curve and the returned HKDF salt/info.
The verify operation is for HMAC; RSA/ECDSA signatures are verified on the host.
Payload capacity includes command fields and length prefixes, not only message bytes.

Compare your input with the mechanism details and wire layouts.