phacility/phabricator · error · Exception

Keyring configuration has an invalid key specification

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.

Solutions

Match the exact field set: name (string), type (string), material.base64 (string), default (optional bool)
Read the %s suffix of the message — it is the PhutilTypeSpec error naming the bad field and expected type
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}]

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Use exactly the four allowed fields: name, type, material.base64, default
Booleans must be JSON true/false, not "true"/"false" strings
Run the PhutilTypeSpec check in config pipelines to catch field errors before deployment

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: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: 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)