yiisoft/yii2 · error · InvalidConfigException

Failed to generate HMAC with hash algorithm: {macHash}

Error message

Failed to generate HMAC with hash algorithm: {macHash}

What it means

Security::hashData() computes hash_hmac() under the component's macHash and throws InvalidConfigException when the call returns falsy, which happens when macHash names an algorithm the hash extension does not recognize. The shipped default ('sha-256') works on standard builds, so in practice this error means macHash was customized to a misspelled or unavailable name (e.g. 'sha3512', or an algorithm not compiled into the runtime).

Source

Thrown at framework/base/Security.php:353

     * There is no need to hash inputs or outputs of [[encryptByKey()]] or [[encryptByPassword()]]
     * as those methods perform the task.
     * @param string $data the data to be protected
     * @param string $key the secret key to be used for generating hash. Should be a secure
     * cryptographic key.
     * @param bool $rawHash whether the generated hash value is in raw binary format. If false, lowercase
     * hex digits will be generated.
     * @return string the data prefixed with the keyed hash
     * @throws InvalidConfigException when HMAC generation fails.
     * @see validateData()
     * @see generateRandomKey()
     * @see hkdf()
     * @see pbkdf2()
     */
    public function hashData($data, $key, $rawHash = false)
    {
        $hash = hash_hmac($this->macHash, $data, $key, $rawHash);
        if (!$hash) {
            throw new InvalidConfigException('Failed to generate HMAC with hash algorithm: ' . $this->macHash);
        }

        return $hash . $data;
    }

    /**
     * Validates if the given data is tampered.
     * @param string $data the data to be validated. The data must be previously
     * generated by [[hashData()]].
     * @param string $key the secret key that was previously used to generate the hash for the data in [[hashData()]].
     * function to see the supported hashing algorithms on your system. This must be the same
     * as the value passed to [[hashData()]] when generating the hash for the data.
     * @param bool $rawHash this should take the same value as when you generate the data using [[hashData()]].
     * It indicates whether the hash value in the data is in binary format. If false, it means the hash value consists
     * of lowercase hex digits only.
     * hex digits will be generated.
     * @return string|false the real data with the hash stripped off. False if the data is tampered.
     * @throws InvalidConfigException when HMAC generation fails.

View on GitHub (pinned to 66f00d18a2)

Solutions

1. Reset macHash to the default 'sha-256' or pick a name from hash_hmac_algos() in the target runtime
2. Validate the configured name with in_array($macHash, hash_hmac_algos(), true) at bootstrap
3. If changing macHash deliberately, re-issue data hashed under the old algorithm (cookies/tokens signed by hashData will otherwise fail validation)

Example fix

// before
'components' => [
    'security' => ['macHash' => 'sha-512-hmac'], // not a real algorithm name
],

// after
'components' => [
    'security' => ['macHash' => 'sha-256'],
],

if (!in_array(Yii::$app->security->macHash, hash_hmac_algos(), true)) {
    throw new \RuntimeException('macHash not supported: ' . Yii::$app->security->macHash);
}
$signed = Yii::$app->security->hashData($data, $key);

try {
    $signed = Yii::$app->security->hashData($data, $key);
} catch (\yii\base\InvalidConfigException $e) {
    // unsupported macHash — environment config error, no retry
}

When it happens

Trigger: 'components' => ['security' => ['macHash' => 'sha512-hmac']] (not an algorithm name); switching macHash to an exotic hash not present in hash_hmac_algos() on the target build; per-environment config where only one environment sets a bad value.

Common situations: Compliance-driven algorithm changes without verifying the runtime; config copied from other projects; typos in environment-specific security blocks.

Related errors

• Failed to generate HMAC with hash algorithm:
• {cipher} is not an allowed cipher
• Invalid parameters to hash_hkdf()
• Invalid parameters to hash_pbkdf2()
• Invalid validation rule: a rule must specify both attribute

AI-assisted analysis of yiisoft/yii2@66f00d18a2 (2026-08-17). Data as JSON: /api/errors/ab669b727157055b. Report an issue: GitHub.