{"record":{"id":"513557a0b658d220","repo":"apple/pkl","slug":"vmutils-tovmexception-e-source-modulename","errorCode":null,"errorMessage":"VmUtils.toVmException(e, source, moduleName)","messagePattern":"VmUtils\\.toVmException\\(e, source, moduleName\\)","errorType":"exception","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/builder/ImportsAndReadsParser.java","lineNumber":76,"sourceCode":"      boolean isModule,\n      boolean isGlob,\n      boolean isExtends,\n      boolean isAmends,\n      String stringValue,\n      SourceSection sourceSection) {}\n\n  /** Parses a module, and collects all imports and reads. */\n  public static List<Entry> parse(ModuleKey moduleKey, ResolvedModuleKey resolvedModuleKey)\n      throws IOException {\n    var parser = new Parser();\n    var text = resolvedModuleKey.loadSource();\n    var source = VmUtils.createSource(moduleKey, text);\n    var importListParser = new ImportsAndReadsParser(source);\n    try {\n      return parser.parseModule(text).accept(importListParser);\n    } catch (ParserError e) {\n      var moduleName = IoUtils.inferModuleName(moduleKey);\n      throw VmUtils.toVmException(e, source, moduleName);\n    }\n  }\n\n  public ImportsAndReadsParser(Source source) {\n    super(source);\n  }\n\n  @Override\n  protected VmExceptionBuilder exceptionBuilder() {\n    return new VmExceptionBuilder();\n  }\n\n  @Override\n  public @Nullable List<Entry> visitExtendsOrAmendsClause(ExtendsOrAmendsClause decl) {\n    var importStr = decl.getUrl().getString();\n    var sourceSection = createSourceSection(decl.getUrl());\n    return Collections.singletonList(\n        new Entry(","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/builder/ImportsAndReadsParser.java#L58-L94","documentation":"When scanning a module solely for its imports and `read(...)` expressions, a ParserError from the Pkl parser is converted via VmUtils.toVmException into a PklException carrying the source, module name, and formatted diagnostic. This wraps raw parser errors so they surface with proper file/line/span information to the evaluator caller.","triggerScenarios":"Calling the import/read extraction entry point (parser.parseModule(text).accept(importListParser)) on text that is not syntactically valid Pkl for the given moduleKey.","commonSituations":"Loading a module from a cache or network with truncated/corrupted content; pointing a dependency at a non-Pkl file (HTML error page, YAML); running with an older Pkl version than the module syntax requires.","solutions":["Read the converted VmException message — it contains the span and caret pointing at the syntax error; fix that line in the module.","Verify the moduleKey resolves to actual Pkl source (not an error page or binary).","Confirm the Pkl version used supports the syntax in the module (e.g. new features).","Validate the file standalone with `pkl eval <file>` to reproduce the parse error."],"exampleFix":"// before\nImportGraph.scan(moduleKey, htmlErrorPage)\n// after\nval text = fetchPklSource(moduleKey) // ensure text/*.pkl content\nImportGraph.scan(moduleKey, text)","handlingStrategy":"try-catch","validationCode":"// Verify source is plausibly Pkl before parsing imports\nif (!text.contains(\"module\") && !text.contains(\"=\")) throw new IOException(\"Not Pkl source: \" + moduleKey);","typeGuard":null,"tryCatchPattern":"try {\n  ImportGraph.scan(moduleKey, text);\n} catch (PklException e) {\n  logger.error(\"Import scan failed for {}: {}\", moduleKey, e.getMessage());\n}","preventionTips":["Ensure fetched module content is text/plain Pkl, not an HTML error page.","Pin dependency module versions compatible with your Pkl runtime.","Validate modules standalone with `pkl eval` before adding them to dependency graphs."],"tags":["pkl","parser","module-loading"],"backgroundTag":"json-parse-error","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}