{"record":{"id":"e1d527ab92f40a52","repo":"apple/pkl","slug":"invalidschemeinpackageuri","errorCode":"invalidSchemeInPackageUri","errorMessage":"invalidSchemeInPackageUri","messagePattern":"invalidSchemeInPackageUri","errorType":"error_code","errorClass":"URISyntaxException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/packages/PackageUri.java","lineNumber":51,"sourceCode":"    try {\n      return new PackageUri(baseUri);\n    } catch (URISyntaxException e) {\n      throw new IllegalArgumentException(e);\n    }\n  }\n\n  public PackageUri(String baseUri) throws URISyntaxException {\n    this(new URI(baseUri));\n  }\n\n  public PackageUri(URI uri) throws URISyntaxException {\n    if (uri.isOpaque()) {\n      throw new URISyntaxException(\n          uri.toString(), ErrorMessages.create(\"invalidModuleUriMissingSlash\", uri, \"package\"));\n    }\n    var scheme = uri.getScheme();\n    if (scheme == null || !(scheme.equals(\"package\") || scheme.equals(\"projectpackage\"))) {\n      throw new URISyntaxException(\n          uri.toString(), ErrorMessages.create(\"invalidSchemeInPackageUri\", scheme));\n    }\n    var authority = uri.getAuthority();\n    if (authority == null || authority.isEmpty()) {\n      throw new URISyntaxException(\n          uri.toString(), ErrorMessages.create(\"missingAuthorityInPackageUri\", uri));\n    }\n    var path = uri.getPath();\n    if (path == null || path.isEmpty()) {\n      throw new URISyntaxException(\n          uri.toString(), ErrorMessages.create(\"missingPathInPackageUri\", uri));\n    }\n    // reject `..` segments, percent-encoded or not\n    for (var segment : path.split(\"/\", -1)) {\n      if (segment.equals(\"..\")) {\n        throw new URISyntaxException(\n            uri.toString(), ErrorMessages.create(\"invalidRelativePathInPackageUri\"));\n      }","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/packages/PackageUri.java#L33-L69","documentation":"Thrown by the PackageUri constructor when a URI passed to it is opaque or uses a scheme other than 'package' or 'projectpackage'. Package URIs in Pkl must be hierarchical URIs with one of those two schemes; anything else is rejected at parse time.","triggerScenarios":"Calling new PackageUri(URI) or PackageUtils.parsePackageUriWithoutChecksums with a URI whose scheme is null, or is not exactly 'package' or 'projectpackage' (e.g. 'https://...', 'pkg://...', or a scheme-less relative path).","commonSituations":"Typos like 'pkg:' instead of 'package:'; hardcoding an https URL of a registry instead of the package: URI; passing a relative path from config where a package URI is expected; forgetting the scheme entirely.","solutions":["Prefix the URI with the correct scheme 'package://' (or 'projectpackage://'), e.g. package://example.com/foo@1.0.0","Fix the scheme spelling to exactly 'package' or 'projectpackage' (case-sensitive equals check)","If you have an opaque URI (no '//'), restructure it as scheme://authority/path","Verify you are not passing an https:// registry URL where a package: URI is required"],"exampleFix":"// before\nvar uri = URI.create(\"https://example.com/my-pkg@1.2.3\");\nvar pkg = new PackageUri(uri);\n// after\nvar uri = URI.create(\"package://example.com/my-pkg@1.2.3\");\nvar pkg = new PackageUri(uri);","handlingStrategy":"validation","validationCode":"boolean hasValidPackageUriScheme(URI uri) {\n  var scheme = uri.getScheme();\n  return !uri.isOpaque() && (\"package\".equals(scheme) || \"projectpackage\".equals(scheme));\n}","typeGuard":"static boolean isPackageUri(URI uri) {\n  return !uri.isOpaque() && (\"package\".equals(uri.getScheme()) || \"projectpackage\".equals(uri.getScheme()));\n}","tryCatchPattern":"try {\n  var pkg = new PackageUri(uri);\n} catch (URISyntaxException e) {\n  throw new IllegalArgumentException(\"Not a valid package URI (bad scheme): \" + uri, e);\n}","preventionTips":["Always use 'package://' when writing package URIs","Never substitute https:// registry URLs for package: URIs","Validate scheme with a helper before constructing PackageUri"],"tags":["pkl","package-uri","uri-validation","scheme"],"backgroundTag":"invalid-url-format","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}