phacility/phabricator · error · Exception

Almanac service, device, property, network and namespace nam

Error message

Almanac service, device, property, network and namespace names must be at least 3 characters long.

What it means

AlmanacNames::validateName() enforces the shared naming contract for Almanac services, devices, properties, networks and namespaces. The first rule rejects names shorter than 3 characters, because names are used as DNS-like identifiers and single/double-character names are reserved or too collision-prone.

Source

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

<?php

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

View on GitHub (pinned to 5720a38cfe)

Solutions

Choose a name of at least 3 characters, e.g. 'db1' instead of 'db' or 'w1' -> 'web01'.
If importing existing inventory, transform names during import to satisfy the minimum length.
Check the other rules in AlmanacNames::validateName() at the same time so the retry passes all of them (length <= 100, charset, segment rules).

Example fix

// before
$device->setName('db');   // throws: must be at least 3 characters

// after
$device->setName('db1');  // passes minimum length

Defensive patterns

Strategy: validation

Validate before calling

function almanacNameMeetsLengthRule($name) {
  $len = strlen($name);
  return $len >= 3 && $len <= 100;
}
// if (!almanacNameMeetsLengthRule($name)) { /* reject with clear message */ }

Type guard

function isValidAlmanacNameLength($name) {
  return strlen($name) >= 3;
}

Try / catch

try {
  AlmanacNames::validateName($name);
} catch (Exception $ex) {
  // Surface which rule failed to the form/API caller so they can fix the input.
  $errors[] = $ex->getMessage();
}

Prevention

Validate names client-side/API-side with the same 3-character minimum before calling create.
Never provision single- or double-character identifiers; pick a naming convention with room.
Run AlmanacNames::validateName() in a dry-run pass when bulk-importing inventory.

When it happens

Trigger: Creating or renaming any named Almanac object with strlen($name) < 3, e.g. 'db', 'w1', or an empty string, through the UI, Conduit API, or CLI.

Common situations: Scripted provisioning trying to create short host aliases; fat-fingered empty form submit; migrating inventory that used 2-letter rack codes.

Related errors

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