apple/pkl · error · VmException

cannotFindStdLibModule

cannotFindStdLibModule

Error message

cannotFindStdLibModule

What it means

ModuleCache.getOrLoad throws cannotFindStdLibModule when a `pkl:`-scheme stdlib import names a module that does not exist in the current Pkl release's standard library. The error lists all valid standard library module URIs to help pick the right name. It only fires after the switch over known module names falls through and the URI is not in STDLIB_MODULE_URIS.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/ModuleCache.java:125

        case "ref":
          return RefModule.getModule();
        case "reflect":
          return ReflectModule.getModule();
        case "release":
          return ReleaseModule.getModule();
        case "semver":
          return SemVerModule.getModule();
        case "settings":
          // always needed if ~/.config/pkl/settings.pkl is present
          return SettingsModule.getModule();
        case "test":
          return TestModule.getModule();
        case "xml":
          return XmlModule.getModule();
        default:
          if (!STDLIB_MODULE_URIS.contains(moduleKey.getUri())) {
            var stdlibModules = String.join("\n", Release.current().standardLibrary().modules());
            throw new VmExceptionBuilder()
                .withOptionalLocation(importNode)
                .evalError("cannotFindStdLibModule", moduleName, stdlibModules)
                .build();
          }
      }
    }

    if (!moduleKey.isCached()) {
      var resolvedKey = resolve(moduleKey, securityManager, importNode);
      return doLoad(
          moduleKey,
          resolvedKey,
          moduleResolver,
          moduleInstantiator,
          moduleInitializer,
          importNode);
    }

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Compare your import against the module list printed in the error and fix the module name (e.g. `pkl:math`, `pkl:base`).
2. Check the stdlib docs for your installed Pkl version; the module may not exist yet in your release.
3. Upgrade Pkl if the module exists only in newer releases.

Example fix

// before
import "pkl:maths" as maths
// after
import "pkl:math" as maths

val stdlib = setOf("base","math","test","xml","platform","json","yaml","toml","pkl","reflect","internal")
fun isStdlibImport(uri: String) = uri.startsWith("pkl:") && uri.removePrefix("pkl:").split("/").first() in stdlib

When it happens

Trigger: An import like `import "pkl:math2"` (misspelled stdlib module) resolved as a stdlib module key but absent from Release.current().standardLibrary().modules().

Common situations: Typos in `pkl:` imports; using a stdlib module that was renamed or removed between Pkl versions; importing a hypothetical module from documentation of a newer Pkl than installed.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• cannotFindModule
• cannotAnalyzeBecauseSyntaxError
• ioErrorLoadingModule
• invalidGlobPattern
• cannotFindModule

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