phacility/phabricator · error · Exception

Almanac service, device, network, property and namespace nam

Error message

Almanac service, device, network, property and namespace names may not have any segments containing only digits.

What it means

Fourth rule of AlmanacNames::validateName(): no dot-separated segment may consist solely of digits, enforced by /(^|\.)\d+(\z|\.)/. This prevents purely numeric labels, which are ambiguous with numeric IDs and invalid as DNS labels in many resolvers.

Source

Thrown at src/applications/almanac/util/AlmanacNames.php:29

    }

    if (strlen($name) > 100) {
      throw new Exception(
        pht(
          'Almanac service, device, property, network and namespace names '.
          'may not be more than 100 characters long.'));
    }

    if (!preg_match('/^[a-z0-9.-]+\z/', $name)) {
      throw new Exception(
        pht(
          'Almanac service, device, property, network and namespace names '.
          'may only contain lowercase letters, numbers, hyphens, and '.
          'periods.'));
    }

    if (preg_match('/(^|\\.)\d+(\z|\\.)/', $name)) {
      throw new Exception(
        pht(
          'Almanac service, device, network, property and namespace names '.
          'may not have any segments containing only digits.'));
    }

    if (preg_match('/\.\./', $name)) {
      throw new Exception(
        pht(
          'Almanac service, device, property, network and namespace names '.
          'may not contain multiple consecutive periods.'));
    }

    if (preg_match('/\\.-|-\\./', $name)) {
      throw new Exception(
        pht(
          'Almanac service, device, property, network and namespace names '.
          'may not contain hyphens adjacent to periods.'));
    }

View on GitHub (pinned to 5720a38cfe)

Solutions

Prefix numeric segments with a letter: 'db.01.host' -> 'db.n01.host', 'cluster.2' -> 'cluster.v2'.
Adjust generators to always emit at least one letter per segment.
Remember a fully numeric name also trips this rule, not just inner segments.

Example fix

// before
$service->setName('cluster.2'); // throws: digit-only segment

// after
$service->setName('cluster.v2');

Defensive patterns

Strategy: validation

Validate before calling

if (preg_match('/(^|\.)\d+(\z|\.)/', $name)) {
  throw new Exception('No dot-separated segment may be all digits.');
}

Type guard

function hasNoDigitOnlySegments($name) {
  foreach (explode('.', $name) as $segment) {
    if ($segment !== '' && ctype_digit($segment)) {
      return false;
    }
  }
  return true;
}

Try / catch

try {
  AlmanacNames::validateName($name);
} catch (Exception $ex) {
  if (preg_match('/segments containing only digits/', $ex->getMessage())) {
    // prefix numeric segments, e.g. 'cluster.2' -> 'cluster.v2', then re-validate
  } else {
    throw $ex;
  }
}

Prevention

Name generators must inject a letter into every numeric segment (v2, n01, s3).
Test generated names against the full AlmanacNames rule set in CI.
Remember a wholly numeric name is also rejected by this rule.

When it happens

Trigger: Names like 'db.01.host', 'cluster.2', or '123' where any segment between dots (including the whole name) is all digits.

Common situations: Auto-numbering schemes that zero-pad segments ('node.001'); names built by joining numeric shard IDs with dots.

Related errors

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