apple/pkl · error · VmException

incompatiblePklVersion

incompatiblePklVersion

Error message

incompatiblePklVersion

What it means

MinPklVersionChecker.doCheck throws incompatiblePklVersion when a module declares `minPklVersion` greater than the currently running Pkl version. The comparison uses the current major.minor.patch version against the required version, and the error reports the module name, required version, and current version. It is a deliberate compatibility gate, not a failure of the module itself.

Source

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

        Version version;
        try {
          version = Version.parse(versionText.substring(1, versionText.length() - 1));
        } catch (IllegalArgumentException e) {
          return;
        }

        doCheck(moduleName, version, importNode);
        return;
      }
    }
  }

  private static void doCheck(
      String moduleName, @Nullable Version requiredVersion, @Nullable Node importNode) {
    if (requiredVersion == null || currentMajorMinorPatchVersion.compareTo(requiredVersion) >= 0)
      return;

    throw new VmExceptionBuilder()
        .withOptionalLocation(importNode)
        .evalError("incompatiblePklVersion", moduleName, requiredVersion, currentVersion)
        .build();
  }

  private static @Nullable String getLastIdText(@Nullable Type type) {
    if (!(type instanceof DeclaredType declType)) return null;
    var identifiers = declType.getName().getIdentifiers();
    return identifiers.get(identifiers.size() - 1).getValue();
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Upgrade the Pkl CLI/runtime to at least the required version named in the error message.
2. If you cannot upgrade, pin the offending dependency to a version whose minPklVersion is compatible.
3. If you own the module, lower `minPklVersion` only if you truly use no newer-language features.

Example fix

// before (shell)
pkl eval script.pkl  # with Pkl 0.26 but module requires 0.27
// after
pkl --version  # upgrade first, e.g. via package manager
pkl eval script.pkl

// shell pre-check
pkl --version | awk -v req="0.27.0" -F. 'exit ($2*10000+$3*100+$4 < req ? 1 : 0)' || echo "upgrade Pkl"

try {
  evaluator.evaluate(moduleSource)
} catch (e: PklException) {
  if (e.message?.contains("minPklVersion") == true) fail("upgrade Pkl: " + e.message)
  throw e
}

When it happens

Trigger: Importing/evaluating a module whose `minPklVersion = "X.Y.Z"` property exceeds the interpreter's version; doCheck is invoked from check() during module load when the import graph contains such a module.

Common situations: Running an older Pkl CLI or embedded runtime against modules written for a newer Pkl release; CI pins an old Pkl version while dependencies bump minPklVersion; a dependency library raised its minPklVersion.

Related errors

• VmUtils.toVmException(e, source, moduleName)
• Node `%s` of type `%s` does not have a property named `%s`.
• JavaType token must be parameterized.
• Leaf node `%s` of type `%s` does not have a child named `%s`
• Node `%s` of type `%s` does not have a key named `%s`. Avail

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