phacility/phabricator · error · Exception

Almanac service, device, property, network and namespace nam

Error message

Almanac service, device, property, network and namespace names may only contain lowercase letters, numbers, hyphens, and periods.

What it means

Third rule of AlmanacNames::validateName(): the entire name must match /^[a-z0-9.-]+\z/. Uppercase letters, underscores, spaces, slashes and every other character are rejected so names stay valid across DNS, URLs and shell contexts.

Source

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

final class AlmanacNames extends Phobject {

  public static function validateName($name) {
    if (strlen($name) < 3) {
      throw new Exception(
        pht(
          'Almanac service, device, property, network and namespace names '.
          'must be at least 3 characters long.'));
    }

    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.'));

View on GitHub (pinned to 5720a38cfe)

Solutions

Use only lowercase letters, digits, hyphens and periods: 'web-01' not 'Web_01'.
Normalize programmatically: $name = strtolower($name); $name = preg_replace('/[^a-z0-9.-]+/', '-', $name); before submission.
Trim input first; trailing whitespace/newlines fail this regex too.

Example fix

// before
$device->setName('Web_Node #1'); // throws: invalid characters

// after
$name = strtolower('Web_Node #1');
$name = preg_replace('/[^a-z0-9.-]+/', '-', $name);
$device->setName('web-node-1');

Defensive patterns

Strategy: validation

Validate before calling

if (!preg_match('/^[a-z0-9.-]+\z/', $name)) {
  throw new Exception('Name may only contain lowercase letters, digits, hyphens and periods.');
}

Type guard

function hasValidAlmanacNameCharset($name) {
  return (bool)preg_match('/^[a-z0-9.-]+\z/', $name);
}

Try / catch

try {
  AlmanacNames::validateName($name);
} catch (Exception $ex) {
  if (preg_match('/may only contain lowercase/', $ex->getMessage())) {
    $name = preg_replace('/[^a-z0-9.-]+/', '-', strtolower($name));
    AlmanacNames::validateName($name); // re-run full rule set
  } else {
    throw $ex;
  }
}

Prevention

Lowercase and slugify all operator input before creating Almanac objects.
Ban underscores in host/service naming conventions from day one.
Trim whitespace and strip newlines from pasted names.

When it happens

Trigger: Submitting a name containing uppercase letters ('Web-01'), underscores ('web_01'), spaces, or any non [a-z0-9.-] character such as colons or unicode.

Common situations: Copy-pasting hostnames containing underscores from inventory; teams used to AWS-style names with capital letters; trailing whitespace or newline sneaking in from form input.

Related errors

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