phacility/phabricator · error · Exception

Version name "%s" is not valid: version names may only conta

Error message

Version name "%s" is not valid: version names may only contain latin letters, digits, periods, and hyphens.

What it means

Thrown by PhabricatorPackagesVersion::assertValidVersionName() when the version name contains characters outside /^[A-Za-z0-9.-]+\z/. Only latin letters, digits, periods, and hyphens are allowed; spaces, underscores, plus signs (semver build metadata), slashes, and multibyte characters are rejected.

Source

Thrown at src/applications/packages/storage/PhabricatorPackagesVersion.php:81

    if (!$length) {
      throw new Exception(
        pht(
          'Version name "%s" is not valid: version names are required.',
          $value));
    }

    $max_length = 64;
    if ($length > $max_length) {
      throw new Exception(
        pht(
          'Version name "%s" is not valid: version names must not be '.
          'more than %s characters long.',
          $value,
          new PhutilNumber($max_length)));
    }

    if (!preg_match('/^[A-Za-z0-9.-]+\z/', $value)) {
      throw new Exception(
        pht(
          'Version name "%s" is not valid: version names may only contain '.
          'latin letters, digits, periods, and hyphens.',
          $value));
    }

    if (preg_match('/^[.-]|[.-]$/', $value)) {
      throw new Exception(
        pht(
          'Version name "%s" is not valid: version names may not start or '.
          'end with a period or hyphen.',
          $value));
    }
  }


/* -(  PhabricatorSubscribableInterface  )----------------------------------- */

View on GitHub (pinned to 5720a38cfe)

Solutions

Sanitize the name: keep only [A-Za-z0-9.-], mapping underscores and spaces to hyphens.
Drop semver '+' build metadata from the name and record it elsewhere (e.g. description).
Validate against ^[A-Za-z0-9.-]+$ before applying version transactions.

Example fix

// before
$name = '1.0.0-beta+1';

// after
$name = preg_replace('/[^A-Za-z0-9.-]+/', '-', '1.0.0-beta+1');
// $name is now '1.0.0-beta-1-'
$name = trim($name, '.-');
PhabricatorPackagesVersion::assertValidVersionName($name);

Defensive patterns

Strategy: validation

Validate before calling

$name = preg_replace('/[^A-Za-z0-9.-]+/', '-', $raw_name);
$name = trim($name, '.-');
if (!preg_match('/^[A-Za-z0-9.-]+\z/', $name)) {
  // reject - cannot be represented
}
PhabricatorPackagesVersion::assertValidVersionName($name);

Type guard

function is_valid_version_charset($name) {
  return is_string($name)
    && preg_match('/^[A-Za-z0-9.-]+\z/', $name) === 1;
}

Try / catch

try {
  PhabricatorPackagesVersion::assertValidVersionName($name);
} catch (Exception $ex) {
  $errors[] = $ex->getMessage();
}

Prevention

Strip semver '+' build metadata from tags before importing them as version names.
Normalize spaces and underscores to hyphens in one sanitization step.
Reject VCS ref names containing slashes early (they indicate a branch path, not a version).

When it happens

Trigger: Submitting a version name such as '1.0.0-beta+1' (rejected '+'), 'v1.0 (stable)' (spaces/parens), 'release_2' (underscore), or a unicode tag like 'verze 1' through the version editor or import path.

Common situations: Importing tags from VCS tools that allow arbitrary ref characters; semver strings with '+' build metadata; localized version labels; scripts converting spaces to underscores instead of hyphens.

Related errors

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