phacility/phabricator · error · Exception

Atom names must not be in the form '%s'. This pattern is res

Error message

Atom names must not be in the form '%s'. This pattern is reserved for disambiguating atoms with similar names.

What it means

DivinerAtomRef::setName() normalizes the name and rejects anything matching /^@\d+\z/, such as '@123'. Diviner appends @N suffixes itself when disambiguating atoms with identical names, so that pattern is reserved for its generated output; user-defined atoms must not collide with it or name-based lookups would be ambiguous.

Source

Thrown at src/applications/diviner/atom/DivinerAtomRef.php:47

  }

  public function getIndex() {
    return $this->index;
  }

  public function setSummary($summary) {
    $this->summary = $summary;
    return $this;
  }

  public function getSummary() {
    return $this->summary;
  }

  public function setName($name) {
    $normal_name = self::normalizeString($name);
    if (preg_match('/^@\d+\z/', $normal_name)) {
      throw new Exception(
        pht(
          "Atom names must not be in the form '%s'. This pattern is ".
          "reserved for disambiguating atoms with similar names.",
          '/@\d+/'));
    }
    $this->name = $normal_name;
    return $this;
  }

  public function getName() {
    return $this->name;
  }

  public function setType($type) {
    $this->type = self::normalizeString($type);
    return $this;
  }

View on GitHub (pinned to 5720a38cfe)

Solutions

Rename the atom to anything not of the form @<digits> (drop the leading '@' or add a word)
Audit the generator that produced the name - usually an annotation like @123 was misread as a name
Add a rename/mapping step when importing external docs whose identifiers are purely numeric

Example fix

// before
$atom_ref->setName('@123');

// after: any name not matching /^@\d+\z/
$atom_ref->setName('Example_123');

Defensive patterns

Strategy: validation

Validate before calling

$normal = DivinerAtomRef::normalizeString($name);
if (preg_match('/^@\d+\z/', $normal)) {
  throw new Exception('Atom names may not look like @<digits>.');
}

Type guard

function isAcceptableAtomName($name) {
  if (!is_string($name)) {
    return false;
  }
  $normal = DivinerAtomRef::normalizeString($name);
  return !preg_match('/^@\d+\z/', $normal);
}

Prevention

Validate atom names at the source (annotation parsing) rather than waiting for setName() to throw
Document the reserved @<digits> pattern in generator templates so contributors never pick such names

When it happens

Trigger: A documentation generator or Diviner book configuration defines an atom literally named '@123' - typically a misparsed annotation or a name derived from user data - and setName() is called during atom generation.

Common situations: Custom Diviner generators deriving atom names from files or annotations; migrations producing numeric-at identifiers; hand-written atom refs in Diviner configuration.

Related errors

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