apple/pkl · error · URISyntaxException

ErrorMessages.create("")

Error message

ErrorMessages.create("")

What it means

CanonicalPackageUri.of() parses a canonical package URI of the form baseUri@majorVersion. If the text after '@' cannot be parsed as an integer (the major version), a URISyntaxException with an EMPTY message is thrown. The empty message is a bug/oversight — it gives the caller no clue about what failed.

Solutions

1. Fix the URI so the part after '@' is a plain integer major version (e.g. package://example.com/foo@1)
2. Check that the '@' separator is present and the string after it is not empty
3. If constructing programmatically, validate the version with Integer.parseInt before building the URI
4. Report/patch the empty ErrorMessages.create("") to include the URI and expected format

Example fix

// before
String uri = "package://example.com/my.pkg@";
// after
String uri = "package://example.com/my.pkg@1";

int at = uri.indexOf('@');
if (at < 0 || !uri.substring(at + 1).matches("\\d+")) throw new IllegalArgumentException("package URI must end in @<majorVersion>: " + uri);

boolean isValidPackageUri(String uri) { int at = uri.lastIndexOf('@'); return at > 0 && uri.substring(at + 1).matches("\\d+"); }

try { return CanonicalPackageUri.of(uri); } catch (URISyntaxException e) { throw new IllegalArgumentException("invalid package URI (expected base@majorVersion): " + uri, e); }

When it happens

Trigger: Calling CanonicalPackageUri.of(uriStr) with a URI whose suffix after '@' is non-numeric or empty, e.g. 'package://example.com/foo@' or 'package://example.com/foo@abc'.

Common situations: Hand-typed package URIs in PklProject files or CLI arguments; copying URIs with a trailing '@'; programmatic URI construction concatenating base URI and version where the version variable is empty or malformed.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Failed to parse Pkl module URI
• Failed to parse Pkl module URI
• Cannot generate documentation for just one module within a…
• Cannot resolve relative URI
• cannotAnalyzeRelativeModuleUri

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

Appendix: source

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

              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;
  }

  /**
   * @deprecated As of 0.28.0, replaced by {@link #baseUri()}.
   */
  @Deprecated(forRemoval = true)
  public URI getBaseUri() {

View on GitHub (pinned to f3efcbfc9b)