phacility/phabricator · error · Exception

Keyring configuration has an invalid key specification (at i

Error message

Keyring configuration has an invalid key specification (at index "%s"): %s.

What it means

Each key dictionary in the keyring config is checked with PhutilTypeSpec::checkMap() against the exact schema {name: string, type: string, material.base64: string, default: optional bool}. This error wraps any schema violation and includes the list index plus the underlying spec message, which names the offending field. Unknown keys and wrong scalar types are both rejected.

Source

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

            $index));
      }
    }


    $map = array();
    $defaults = array();
    foreach ($value as $index => $spec) {
      try {
        PhutilTypeSpec::checkMap(
          $spec,
          array(
            'name' => 'string',
            'type' => 'string',
            'material.base64' => 'string',
            'default' => 'optional bool',
          ));
      } catch (Exception $ex) {
        throw new Exception(
          pht(
            'Keyring configuration has an invalid key specification (at '.
            'index "%s"): %s.',
            $index,
            $ex->getMessage()));
      }

      $name = $spec['name'];
      if (isset($map[$name])) {
        throw new Exception(
          pht(
            'Keyring configuration is invalid: it describes multiple keys '.
            'with the same name ("%s"). Each key must have a unique name.',
            $name));
      }
      $map[$name] = true;

      if (idx($spec, 'default')) {

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Match the exact field set: name (string), type (string), material.base64 (string), default (optional bool)
2. Read the %s suffix of the message — it is the PhutilTypeSpec error naming the bad field and expected type
3. Remove extra fields; Phabricator rejects unknown keys rather than ignoring them

Example fix

// before
[{"name": "prod", "type": "aes-256-cbc", "material": "...==", "default": "true"}]

// after
[{"name": "prod", "type": "aes-256-cbc", "material.base64": "...==", "default": true}]

// Mirror the schema check before saving:
PhutilTypeSpec::checkMap(
  $spec,
  array(
    'name' => 'string',
    'type' => 'string',
    'material.base64' => 'string',
    'default' => 'optional bool',
  ));

When it happens

Trigger: An entry missing material.base64; using 'material' instead of 'material.base64'; name given as a number instead of a string; adding an undocumented extra field such as 'comment'; default set to "true" (string) instead of true (bool).

Common situations: Hand-writing or templating the keyring JSON; field names remembered from an older document; YAML-to-JSON conversion coercing booleans to strings.

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 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/d90d5a2de0c05844. Report an issue: GitHub.