apple/pkl · error · URISyntaxException

missingVersionInPackageUri

missingVersionInPackageUri

Error message

ErrorMessages.create("missingVersionInPackageUri", uriStr)

What it means

Thrown by CanonicalPackageUri.of(String) when the URI string contains no '@' separator, so no version can be extracted. Canonical package URIs require an '@<majorVersion>' suffix to compute the canonical major-version form.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/project/CanonicalPackageUri.java:58

              "package",
              // userinfo isn't considered part of the package identifier.
              null,
              uri.getHost(),
              uri.getPort(),
              packageUri.getPathWithoutVersion(),
              // query params aren't considered part of the package identifier.
              null,
              null);
    } catch (URISyntaxException e) {
      throw PklBugException.unreachableCode();
    }
    return new CanonicalPackageUri(baseUri, packageUri.getVersion().getMajor());
  }

  public static CanonicalPackageUri of(String uriStr) throws URISyntaxException {
    var versionIdx = uriStr.lastIndexOf('@');
    if (versionIdx == -1) {
      throw new URISyntaxException(
          uriStr, ErrorMessages.create("missingVersionInPackageUri", uriStr));
    }
    int majorVersion;
    try {
      majorVersion = Integer.parseInt(uriStr.substring(versionIdx + 1));
    } catch (NumberFormatException e) {
      throw new URISyntaxException(uriStr, ErrorMessages.create(""));
    }
    var baseUri = new URI(uriStr.substring(0, versionIdx));
    return new CanonicalPackageUri(baseUri, majorVersion);
  }

  /**
   * @deprecated As of 0.28.0, replaced by {@link #majorVersion()}.
   */
  @Deprecated(forRemoval = true)
  public int getMajorVersion() {
    return majorVersion;

View on GitHub (pinned to f3efcbfc9b)

Solutions

Include the version in the input string, e.g. 'package://example.com/my-pkg@1.2.3'
Ensure the version-bearing portion is not stripped by preprocessing code
Parse with full PackageUri and use the other CanonicalPackageUri.of overload that accepts a parsed PackageUri

Example fix

// before
var canonical = CanonicalPackageUri.of("package://example.com/my-pkg");
// after
var canonical = CanonicalPackageUri.of("package://example.com/my-pkg@1.2.3");

Defensive patterns

Strategy: validation

Validate before calling

boolean canCanonicalize(String uriStr) {
  if (uriStr == null) return false;
  int idx = uriStr.lastIndexOf('@');
  if (idx == -1) return false;
  try { Integer.parseInt(uriStr.substring(idx + 1)); return true; }
  catch (NumberFormatException e) { return false; }
}

Try / catch

try {
  var canonical = CanonicalPackageUri.of(uriStr);
} catch (URISyntaxException e) {
  throw new IllegalArgumentException("Package URI missing '@<version>': " + uriStr, e);
}

Prevention

Pass the full versioned URI string, never a bare package name
Keep the '@version' suffix through any preprocessing
Prefer the CanonicalPackageUri.of(PackageUri) overload for parsed URIs

When it happens

Trigger: Calling CanonicalPackageUri.of(uriStr) with a version-less string like 'package://example.com/my-pkg'; lastIndexOf('@') returns -1.

Common situations: Passing a bare package name or registry base URI instead of the full versioned URI; code that strips the version before canonicalization; legacy configs predating version pinning.

Related errors

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/9e152891264b0271. Report an issue: GitHub.