apple/pkl · error · SecurityManagerException

resourceNotInAllowList|moduleNotInAllowList

resourceNotInAllowList|moduleNotInAllowList

Error message

resourceNotInAllowList|moduleNotInAllowList

What it means

Pkl's security manager blocks module or resource imports whose URI is not explicitly listed in the allowedModules/allowedResources allow lists. checkRead throws SecurityManagerException with messageKey resourceNotInAllowList (for resources) or moduleNotInAllowList (for modules). This is the sandboxing mechanism that prevents pkl code from loading arbitrary external modules or resources.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/SecurityManagers.java:219

        }
        return path.toAbsolutePath();
      } catch (IOException e) {
        throw new UncheckedIOException(e);
      }
    }

    private void checkRead(URI uri, List<Pattern> allowedPatterns, boolean isResource)
        throws SecurityManagerException {
      for (var pattern : allowedPatterns) {
        if (pattern.matcher(uri.toString()).lookingAt()) {
          checkIsUnderRootDir(uri, isResource);
          return;
        }
      }

      var messageKey = isResource ? "resourceNotInAllowList" : "moduleNotInAllowList";
      var message = ErrorMessages.create(messageKey, uri);
      throw new SecurityManagerException(message);
    }

    private void checkIsUnderRootDir(URI uri, boolean isResource) throws SecurityManagerException {
      // handle jar:file: URIs correctly:
      var checkUri =
          uri.getScheme().equals("jar") ? IoUtils.createUri(uri.getSchemeSpecificPart()) : uri;

      if (!checkUri.isAbsolute()) {
        throw new AssertionError("Expected absolute URI but got: " + checkUri);
      }

      if (rootDir == null || !checkUri.getScheme().equals("file")) return;

      var path = Path.of(checkUri);

      // uri represents a UNC path if authority is non-null
      // so treat this like a potentially redirected HTTP read:
      // check if both the given and real paths are under rootDir

View on GitHub (pinned to f3efcbfc9b)

Solutions

Add the offending URI (or a glob pattern covering it) to allowedModules/allowedResources in the SecurityManagers.StandardBuilder.
When using the CLI, pass --allowed-modules and/or --allowed-resources with the module/resource path being loaded.
Inspect the full URI in the exception message and confirm scheme/authority spelling exactly matches an allow-list entry.

Example fix

// before
new SecurityManagers.StandardBuilder()
    .allowModule("example.com/base@1")
    .build();
// after
new SecurityManagers.StandardBuilder()
    .allowModule("example.com/base@1")
    .allowModule("example.com/geo@1") // module actually imported
    .build();

Defensive patterns

Strategy: validation

Validate before calling

String uri = "example.com/geo@1";
boolean allowed = allowedModules.stream().anyMatch(uri::startsWith);
if (!allowed) throw new IllegalStateException("module not in allow list: " + uri);

Try / catch

try {
  evaluator.evaluateOutputText(moduleUri);
} catch (SecurityManagerException e) {
  if (e.getMessage().contains("NotInAllowList")) {
    // reconfigure allowedModules/allowedResources and retry once
  } else throw e;
}

Prevention

Derive allowedModules/allowedResources automatically from the dependency graph rather than hand-maintaining.
Use glob patterns (e.g. example.com/**) to reduce omissions.
Test security policy with a smoke evaluation in CI.

When it happens

Trigger: Calling checkResolveModule/checkResolveResource/checkReadResource (via SecurityManagers.checkRead) with a URI that matches no entry in the configured allowedModules or allowedResources lists.

Common situations: Running `pkl eval` with --allowed-modules/--allowed-resources that omit a dependency's module path; embedding pkl in an app whose SecurityManager allow list was built for one project and reused for another; a new import added to Pkl code without updating the security policy.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

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