phacility/phabricator · error · Exception

Keyring configuration is not valid: value must be a list of

Error message

Keyring configuration is not valid: value must be a list of encryption keys.

What it means

The 'keyring' config option is validated by PhabricatorKeyringConfigOptionType::validateOption(), which requires the JSON value to decode to a PHP array — a list of encryption key dictionaries. This variant is thrown when the top-level value is not an array at all (a JSON scalar such as a string or number). Validation runs when saving the option via the config application or bin/config.

Source

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

<?php

final class PhabricatorKeyringConfigOptionType
  extends PhabricatorConfigJSONOptionType {

  public function validateOption(PhabricatorConfigOption $option, $value) {
    if (!is_array($value)) {
      throw new Exception(
        pht(
          'Keyring configuration is not valid: value must be a '.
          'list of encryption keys.'));
    }

    foreach ($value as $index => $spec) {
      if (!is_array($spec)) {
        throw new Exception(
          pht(
            'Keyring configuration is not valid: each entry in the list must '.
            'be a dictionary describing an encryption key, but the value '.
            'with index "%s" is not a dictionary.',
            $index));
      }
    }


    $map = array();

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Set the option to a JSON list of key dictionaries (see example) using ./bin/config set keyring '...'
2. Use the web Config UI to save the value, which runs the same validator and shows the error inline before it is stored

Example fix

# before
./bin/config set keyring '"dGhpc2lzMzJieXRlc29ma2V5bWF0ZXJpYWw="'

# after
./bin/config set keyring '[{"name":"prod-2024","type":"aes-256-cbc","material.base64":"dGhpc2lzMzJieXRlc29ma2V5bWF0ZXJpYWw=","default":true}]'

// Validate JSON shape locally before saving the option:
$value = phutil_json_decode($json_string);
if (!is_array($value)) {
  // The keyring must be a JSON list of key dictionaries; fix the payload
  // before ./bin/config set keyring.
}

function isKeyringList($value) {
  return is_array($value);
}

When it happens

Trigger: `./bin/config set keyring '"my-key-material"'` (bare scalar); pasting only the base64 key string as the option value; any non-JSON-array value submitted for the option.

Common situations: First-time keyring setup where the admin pastes just the generated base64 key instead of the documented list-of-dicts structure.

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: 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
• Keyring specifies an invalid key ("%s"): key material should

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