phacility/phabricator · error · Exception

Keyring specifies an invalid key ("%s"): key material should

Error message

Keyring specifies an invalid key ("%s"): key material should be base64 encoded.

What it means

Key material must be supplied base64-encoded: the validator runs base64_decode($material, true) in strict mode and rejects the entry when it returns false. Strict mode fails on any character outside the base64 alphabet or wrong padding, so raw binary, hex strings, or whitespace inside the value all trigger it. The key name is included in the message.

Source

Thrown at src/applications/files/keyring/PhabricatorKeyringConfigOptionType.php:76

        $defaults[] = $name;
      }

      $type = $spec['type'];
      switch ($type) {
        case 'aes-256-cbc':
          if (!function_exists('openssl_encrypt')) {
            throw new Exception(
              pht(
                'Keyring is configured with a "%s" key, but the PHP OpenSSL '.
                'extension is not installed. Install the OpenSSL extension '.
                'to enable encryption.',
                $type));
          }

          $material = $spec['material.base64'];
          $material = base64_decode($material, true);
          if ($material === false) {
            throw new Exception(
              pht(
                'Keyring specifies an invalid key ("%s"): key material '.
                'should be base64 encoded.',
                $name));
          }

          if (strlen($material) != 32) {
            throw new Exception(
              pht(
                'Keyring specifies an invalid key ("%s"): key material '.
                'should be 32 bytes (256 bits) but has length %s.',
                $name,
                new PhutilNumber(strlen($material))));
          }
          break;
        default:
          throw new Exception(
            pht(

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Generate correct material: php -r 'echo base64_encode(random_bytes(32)), PHP_EOL;' or head -c 32 /dev/urandom | base64
2. Ensure the stored string is pure base64: no quotes inside quotes, no whitespace, standard +/ alphabet, padding kept
3. Re-set the keyring config with the corrected value

Example fix

// before
{"name": "prod", "type": "aes-256-cbc", "material.base64": "a3f1c0ffee...hex..."}

// after
{"name": "prod", "type": "aes-256-cbc", "material.base64": "oPHAD/7m2Xy0Zl+Bq1c8Yk0PM4YfNpLrS4jEwVnN0F0="}

if (base64_decode($material, true) === false) {
  // Material for key "{$name}" is not valid base64; regenerate with
  // base64_encode(random_bytes(32)) before saving the keyring.
}

When it happens

Trigger: Pasting hex (e.g. from openssl rand -hex 32) instead of base64; raw binary in the JSON; base64 with stripped padding or embedded newlines/spaces; a value produced by a generator that URL-encodes first.

Common situations: Generating key material with the wrong tool (hex vs base64 output flags); copy-paste introducing line breaks; values stored in a secret manager that re-encodes them.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• Keyring configuration is not valid: value must be a list of
• Keyring configuration is not valid: each entry in the list m
• Keyring configuration has an invalid key specification (at i
• Keyring configuration is invalid: it describes multiple keys
• Keyring specifies an invalid key ("%s"): key material should

AI-assisted analysis of phacility/phabricator@5720a38cfe (2026-08-21). Data as JSON: /api/errors/9b4b22cac6cfa285. Report an issue: GitHub.