BLOCKEDLOG_HMAC_KEY error in Dolibarr 24: guide and fix

After upgrading to Dolibarr 24.0.0, the administration area shows this message:

Configuration of the module Immutable logs

getClearHMACSecretKey Error: Failed to decode the crypted value of the parameter
BLOCKEDLOG_HMAC_KEY dolcrypt:AES-256-CTR:4de1c82c60feb73e:+evrXBA7Vk1H0qbHmiYaG2W1l6X+AZyTVSG0A88qPQJcvF3uZ8zdKM5tICSsbQ==
using the obfuscation key. A value was found in database but decoding failed.
May be you modified the SIREN used to get the obfuscation key from ping.dolibarr.org
(or old config key $dolibarr_main_instance_unique_id).

The typical reaction is alarming: "Did I break the immutable record? Will I have to re-sign the thousands of historical records?" The answer is no: Dolibarr cannot read the signing key stored in the database, but the history is still intact. This is the case we resolved in production.

What this error is and what it means

The error tells you that the ERP cannot decrypt the key the Immutable Logs module uses to sign new events. It is not data corruption: it is an unreadable key.

Three quick definitions:

• Immutable logs (blockedlog): the Dolibarr module that stores one line per relevant event (invoices, payments, logins…) in llx_blockedlog.
• Chained signature: each row carries a signature that depends on the previous row; if someone touches a row, the following ones no longer match and the system detects it.
• HMAC key: a secret key the module generates when activated and stores encrypted in llx_const as BLOCKEDLOG_HMAC_KEY.

The value is not stored in plain text: dolcrypt:AES-256-CTR:<IV>:<base64 data>. To decrypt it, Dolibarr uses the installation's master key ($dolibarr_main_instance_unique_id from conf.php). If that key is not the one used to encrypt the constant, the value can no longer be read: exactly what the message says.

V1 vs V2, the difference that explains it all

	V1 format (history)	V2 format (new)
Signature	Chained SHA-256 (dol_hash(..., '5'))	hash_hmac('sha256', ..., HMAC key)
Uses the HMAC key?	No	Yes
Version	up to about Dolibarr 20	from v21, always created in v24

This difference explains it all: the history is usually V1 and its signatures do not depend on the HMAC key, so a rotated key does not affect them. The key is the new lock: the V1 data and signatures remain valid; only a key is missing for the new (V2) signatures.

Typical causes

Cause	How to recognize it	Solution
Upgrade from a version with an old encryption scheme	The error appears right after updating; old tms	Regenerate the key
Database restored from another installation (new hosting, migration)	Constant dated before the current hosting	Regenerate or recover the original conf
conf.php regenerated without restoring the ID	The two conf.php files differ in instance_unique_id	Restore the original ID
Multi-company: two rows (entity 0 and 1)	The llx_const query returns 2 rows	Delete the corrupt one

In our case, the instance_unique_id was the same before and after the upgrade and still the decryption returned invalid bytes: the constant had been saved in a previous life of the installation (another hosting, or a version with a different encryption scheme).

Diagnosis in 2 steps

Step 1: look at the constant (1 minute). Run:

SELECT entity, value, tms FROM llx_const WHERE name = 'BLOCKEDLOG_HMAC_KEY';

• One row: the installation's single key (the normal case).
• Two rows (entity 0 and ≥ 1): the module reads ORDER BY entity DESC LIMIT 1; check the one with the highest entity.
• Value prefix: dolcrypt:AES-256-CTR: → old method; <32 hex> → new method.

Step 2: verify the historical chain (2 minutes). Walk through the llx_blockedlog rows by rowid and check that each signature matches the one calculated by the official buildKeyForSignature() function. In our case: 2,580 records verified, 2,580 OK.

The solution: regenerate the key (the history is preserved)

Step 1 — Backup (always).

CREATE TABLE llx_blockedlog_backup AS SELECT * FROM llx_blockedlog;

Step 2 — Delete the constant.

DELETE FROM llx_const WHERE name = 'BLOCKEDLOG_HMAC_KEY';

If there are two rows per entity, delete only the corrupt one:

DELETE FROM llx_const WHERE name='BLOCKEDLOG_HMAC_KEY' AND entity = 1;

Step 3 — Re-enable the module. In Administration → Modules → BlockedLog (Immutable logs), untick the module and tick it again. The module's init(), not finding the constant, generates a new key encrypted with your instance_unique_id.

Step 4 — Verify. Enter the configuration without errors, the list shows the rows under "Validate", and perform a real action: the new line is signed in V2 and chains with the last V1 signature without any alert.

Note: Dolibarr caches the constant per session. Ask connected users to log in again.

What not to do (blacklist)

• Do not delete or truncate llx_blockedlog: you destroy the audit trail for nothing; the old chain was valid.
• Do not change instance_unique_id randomly: it breaks cookies, API keys and all other current encryption.
• Do not re-sign with a "home-made" script: verification requires the exact algorithm of each version; a fake chain is worse than the doubt.
• Do not copy the database to another hosting without the conf.php: the constant travels, but the key does not.

Frequently asked questions

Have I lost the immutable record history? No. V1 signatures do not depend on the HMAC key; the history remains intact and verifiable.

Does it affect API keys, tokens or cookies? If the cause is a restore or a migration, yes: data encrypted with the old key follows the same pattern; check that the API keys work and that users can log in. If the cause is only the scheme, no.

How do I prevent this from happening again in the next upgrade? Full backup (database + conf.php, noting the instance_unique_id), upgrade first in a test environment, and a visit to the module after the upgrade, reviewing each entity in multi-company setups.

Is it a security problem? Third parties cannot exploit it: the key cannot be decrypted, so what it does is stop the recording of new events. It is worth reviewing whether there were unrecorded environment changes, and checking the backups.

Where can I follow this issue? There is an open issue in the Dolibarr tracker with the full analysis and an already integrated PR that fixes the key per entity, in the GitHub mirror of the official repository.

Executive summary

• The "Failed to decode the crypted value of the parameter BLOCKEDLOG_HMAC_KEY" error after an upgrade to Dolibarr 24 is an unreadable signing key problem, not a data problem.
• The history is valid: 2,580/2,580 verified in the case we attended.
• Low-risk solution: backup → delete the constant in llx_const → re-enable the module.
• The new key only signs new events; the previous record is not touched.
• Prevention: always back up with the conf.php included and a test environment for upgrades.

Prefer not to deal with this? We offer expert Dolibarr and cloud ERP support for SMEs with guidance at every update. Considering moving your management to Dolibarr? This free questionnaire tells you whether it fits your company.