apple/pkl · error · InvalidMappingException

Did not find expected Java class `%s` on the classpath for P

Error message

Did not find expected Java class `%s` on the classpath for Pkl class `%s`. Is your generated code up to date?

What it means

ClassRegistry maps Pkl class names to the generated Java classes and loads them reflectively with Class.forName. When the registry knows the Pkl class's Java name but the class cannot be found on the classpath, it throws InvalidMappingException asking whether your generated code is up to date. This is a codegen/classpath synchronization failure, not a bad input value.

Source

Thrown at pkl-config-java/src/main/java/org/pkl/config/java/mapper/ClassRegistry.java:69

  private static final String PREFIX = "org.pkl.config.java.mapper.";

  private static final Set<String> loadedModules = new HashSet<>();

  private ClassRegistry() {}

  static @Nullable Class<?> get(PClassInfo<?> pklClassInfo) {
    var pklModuleName = pklClassInfo.getModuleName();
    var pklClassName = pklClassInfo.getQualifiedName();
    initClassMappings(pklModuleName);
    var javaName = classMappings.getProperty(PREFIX + pklClassInfo.getQualifiedName());
    if (javaName == null) {
      return null;
    }
    try {
      return Class.forName(javaName);
    } catch (ClassNotFoundException e) {
      throw new InvalidMappingException(pklClassName, javaName, e);
    }
  }

  private static void initClassMappings(String pklModuleName) {
    synchronized (lock) {
      if (loadedModules.contains(pklModuleName)) {
        return;
      }
      loadedModules.add(pklModuleName);
      var url =
          ClassRegistry.class.getResourceAsStream(
              CLASSES_DIRECTORY + "/" + IoUtils.encodePath(pklModuleName) + ".properties");
      if (url == null) {
        return;
      }
      try {
        classMappings.load(url);
      } catch (IOException e) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

Run the code generator for the module so the expected Java class exists and is compiled.
Ensure the jar/module containing the generated classes is on the runtime classpath (check dependency scope, e.g. not test-only).
Compare the javaName in the exception message against your generated sources; fix package/name mismatches.
Clean and rebuild to flush stale compiled classes.
If the mapping is genuinely optional, use the registry lookup that tolerates null instead of get().

Example fix

// before: generated class missing, registry throws
Class<?> clazz = ClassRegistry.get().get("my.app.GeneratedConfig");
// after: generate classes first, then fail fast with context
// build.gradle: pkl { generateJavaCode from("pkl/**/*.pkl") }
Class<?> clazz = ClassRegistry.get().get("my.app.GeneratedConfig"); // exists after codegen

Defensive patterns

Strategy: validation

Validate before calling

// verify generated classes are present at startup
static void verifyMappings(String... pklClassNames) {
  for (String name : pklClassNames) {
    if (ClassRegistry.get().get(name) == null) {
      throw new IllegalStateException("missing generated class for " + name
          + "; run the Pkl code generator");
    }
  }
}

Try / catch

try {
  return mapper.map(value, TargetClass.class);
} catch (InvalidMappingException e) {
  throw new BuildConfigurationException(
      "Generated code missing for " + e.getPklClassName()
      + " (expected " + e.getJavaClassName() + "); run codegen and rebuild", e);
}

Prevention

Wire the Pkl code generator into the build so sources are always generated before compile
Ensure generated-code artifacts are a runtime (not test-only) dependency
After renaming packages in generated code, clean the registry-consuming modules and rebuild
Smoke-test mapping of every Pkl module at application startup

When it happens

Trigger: Decoding/unmapping a Pkl value whose module was generated but whose Java classes (or their containing jar) are not on the runtime classpath; running against a stale build where codegen output was deleted or never compiled.

Common situations: Forgetting to run the Pkl code generator (or the maven/gradle task that does) before running the app; the generated sources jar not included as a runtime dependency; package renamed in generated code while a cached registry still expects the old FQN; shaded/ relocated classes breaking Class.forName.

Related errors

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