apple/pkl · error · VmException

cannotAnalyzeBecauseSyntaxError

cannotAnalyzeBecauseSyntaxError

Error message

cannotAnalyzeBecauseSyntaxError

What it means

During import analysis, Pkl parses each imported module to discover its own imports/read() calls. If that parse fails with a VmException (syntax error), the analyzer rethrows cannotAnalyzeBecauseSyntaxError with the module URI, wrapping the original syntax error.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/VmImportAnalyzer.java:90

    resolvedImports.put(moduleUri, resolvedModuleKey.getUri());
    for (var imprt : collectedImports) {
      if (imports.containsKey(imprt.moduleUri)) {
        continue;
      }
      analyzeSingle(imprt.moduleUri, imprt.resolvedModuleKey, context, imports, resolvedImports);
    }
  }

  private static Set<ImportEntry> collectImports(
      ResolvedModuleKey resolvedModuleKey,
      ModuleResolver moduleResolver,
      SecurityManager securityManager) {
    List<Entry> importsAndReads;
    var moduleKey = resolvedModuleKey.getOriginal();
    try {
      importsAndReads = ImportsAndReadsParser.parse(moduleKey, resolvedModuleKey);
    } catch (VmException err) {
      throw new VmExceptionBuilder()
          .evalError("cannotAnalyzeBecauseSyntaxError", moduleKey.getUri())
          .wrapping(err)
          .build();
    } catch (IOException err) {
      throw new VmExceptionBuilder().evalError("ioErrorLoadingModule", moduleKey.getUri()).build();
    }
    var result = new HashSet<ImportEntry>();
    for (var entry : importsAndReads) {
      if (!entry.isModule()) {
        continue;
      }
      try {
        if (entry.isGlob()) {
          var theModuleKey =
              moduleResolver.resolve(moduleKey.resolveUri(IoUtils.toUri(entry.stringValue())));
          var elements =
              GlobResolver.resolveGlob(
                  securityManager,

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Fix the syntax error in the module named by the URI (the wrapped cause shows the exact location)
  2. If the module is external/dependency, update or pin the correct package version
  3. Re-run evaluation after fixing the file

Example fix

// before (broken.pkl)
foo = = 1
// after
foo = 1
Defensive patterns

Strategy: fallback

Try / catch

try { analyzeImports(uri) } catch (e) { if (e.code === 'cannotAnalyzeBecauseSyntaxError') { reportSyntaxError(e.cause) } else throw e }

Prevention

When it happens

Trigger: An imported module contains invalid Pkl syntax; ImportsAndReadsParser.parse() raises a VmException during collectImports.

Common situations: Typos in a dependency module file; editing a module and introducing a syntax error; a stale cached/dependency module that does not parse.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

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