{"record":{"id":"a473cce2c8a5e049","repo":"phacility/phabricator","slug":"atom-names-must-not-be-in-the-form-s-this-patt","errorCode":null,"errorMessage":"Atom names must not be in the form '%s'. This pattern is reserved for disambiguating atoms with similar names.","messagePattern":"Atom names must not be in the form '(.+?)'\\. This pattern is reserved for disambiguating atoms with similar names\\.","errorType":"validation","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"src/applications/diviner/atom/DivinerAtomRef.php","lineNumber":47,"sourceCode":"  }\n\n  public function getIndex() {\n    return $this->index;\n  }\n\n  public function setSummary($summary) {\n    $this->summary = $summary;\n    return $this;\n  }\n\n  public function getSummary() {\n    return $this->summary;\n  }\n\n  public function setName($name) {\n    $normal_name = self::normalizeString($name);\n    if (preg_match('/^@\\d+\\z/', $normal_name)) {\n      throw new Exception(\n        pht(\n          \"Atom names must not be in the form '%s'. This pattern is \".\n          \"reserved for disambiguating atoms with similar names.\",\n          '/@\\d+/'));\n    }\n    $this->name = $normal_name;\n    return $this;\n  }\n\n  public function getName() {\n    return $this->name;\n  }\n\n  public function setType($type) {\n    $this->type = self::normalizeString($type);\n    return $this;\n  }\n","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/phacility/phabricator/blob/5720a38cfe95b00ca4be5016dd0d2f3195f4fa04/src/applications/diviner/atom/DivinerAtomRef.php#L29-L65","documentation":"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.","triggerScenarios":"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.","commonSituations":"Custom Diviner generators deriving atom names from files or annotations; migrations producing numeric-at identifiers; hand-written atom refs in Diviner configuration.","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"],"exampleFix":"// before\n$atom_ref->setName('@123');\n\n// after: any name not matching /^@\\d+\\z/\n$atom_ref->setName('Example_123');","handlingStrategy":"validation","validationCode":"$normal = DivinerAtomRef::normalizeString($name);\nif (preg_match('/^@\\d+\\z/', $normal)) {\n  throw new Exception('Atom names may not look like @<digits>.');\n}","typeGuard":"function isAcceptableAtomName($name) {\n  if (!is_string($name)) {\n    return false;\n  }\n  $normal = DivinerAtomRef::normalizeString($name);\n  return !preg_match('/^@\\d+\\z/', $normal);\n}","tryCatchPattern":null,"preventionTips":["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"],"tags":["phabricator","diviner","documentation","naming","validation","reserved-names"],"backgroundTag":"reserved-name-rejected","analyzedSha":"5720a38cfe95b00ca4be5016dd0d2f3195f4fa04","analyzedAt":"2026-08-21T05:07:25.672Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}