{"record":{"id":"7dcd8d2f7abfdfd9","repo":"apple/pkl","slug":"invalidmoduleuri-7dcd8d","errorCode":"invalidModuleUri","errorMessage":"invalidModuleUri","messagePattern":"invalidModuleUri","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/ModuleResolver.java","lineNumber":82,"sourceCode":"    var underlyingModuleKey = resolve(moduleUri);\n    return ModuleKeys.cached(underlyingModuleKey, text);\n  }\n\n  public ModuleKey resolve(URI moduleUri, @Nullable Node importNode) {\n    if (!moduleUri.isAbsolute()) {\n      throw new VmExceptionBuilder()\n          .withOptionalLocation(importNode)\n          .bug(\"Cannot resolve relative URI `%s`.\", moduleUri)\n          .build();\n    }\n\n    var normalized = moduleUri.normalize();\n    for (var factory : factories) {\n      Optional<ModuleKey> key;\n      try {\n        key = factory.create(normalized);\n      } catch (URISyntaxException e) {\n        throw new VmExceptionBuilder()\n            .withOptionalLocation(importNode)\n            .evalError(\"invalidModuleUri\", moduleUri)\n            .withHint(e.getReason())\n            .build();\n      } catch (ExternalReaderProcessException e) {\n        throw new VmExceptionBuilder()\n            .withOptionalLocation(importNode)\n            .evalError(\"externalReaderFailure\")\n            .withCause(e)\n            .build();\n      } catch (IOException e) {\n        throw new VmExceptionBuilder()\n            .withOptionalLocation(importNode)\n            .evalError(\"ioErrorLoadingModule\")\n            .withCause(e)\n            .build();\n      }\n      if (key.isPresent()) return key.get();","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/ModuleResolver.java#L64-L100","documentation":"When resolving a module URI, Pkl iterates registered ModuleKey factories; if a factory throws URISyntaxException while parsing the normalized URI, the resolver converts it into an eval error 'invalidModuleUri' with the raw URI and the parser's reason as a hint.","triggerScenarios":"Passing a syntactically malformed URI to resolve() (or importing one), e.g. 'file:///a b.pkl' with illegal characters or '%zz' bad percent-encoding, causing factory.create(normalized) to throw URISyntaxException.","commonSituations":"Imports with unescaped spaces or special characters in paths; programmatically built URIs from unvalidated strings; bad percent-encoding in custom-scheme module paths.","solutions":["Fix the URI string: percent-encode spaces and special characters (%20) and fix malformed escape sequences.","In Java code, validate with new URI(str) or use Paths.get(...).toUri() to build a well-formed URI before calling resolve().","Check the hint attached to the error — it names the exact parsing reason."],"exampleFix":"// before\nURI.create(\"file:///my dir/pkg.pkl\");\n// after\nURI.create(\"file:///my%20dir/pkg.pkl\");","handlingStrategy":"validation","validationCode":"try { new URI(moduleUriString); } catch (URISyntaxException e) { /* fix before calling resolve() */ }","typeGuard":null,"tryCatchPattern":"catch (VmException e) { if (\"invalidModuleUri\".equals(e.getCode())) { /* surface hint to user */ } }","preventionTips":["Percent-encode user-supplied path segments (URLEncoder.encode).","Validate URI strings with new URI(...) before importing or resolving."],"tags":["uri","module-resolution","syntax"],"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-17T15:17:12.973Z"}