apple/pkl · warning

'XDG_CACHE_HOME' is an invalid path

Error message

'XDG_CACHE_HOME' is an invalid path: {}

What it means

ExecutorOptions.defaultModuleCacheDir reads XDG_CACHE_HOME to derive the default module cache directory. If the env value cannot be parsed as a filesystem path (InvalidPathException), it logs a warning and falls through to platform defaults (LOCALAPPDATA on Windows, otherwise ~/.cache/pkl).

Solutions

1. Fix XDG_CACHE_HOME to a valid absolute filesystem path (e.g. /home/user/.cache).
2. Unset XDG_CACHE_HOME so executor falls back to the platform default cache dir.
3. On Windows, remove characters invalid in NTFS paths from the value.
4. Check the warning log's cause message for which characters made the path invalid.

Example fix

// before (shell profile)
export XDG_CACHE_HOME="$HOME/.cache/"
# after
export XDG_CACHE_HOME="$HOME/.cache"

String xdg = System.getenv("XDG_CACHE_HOME");
if (xdg != null && !xdg.isEmpty()) {
  try { java.nio.file.Path.of(xdg); } catch (InvalidPathException e) {
    System.err.println("Invalid XDG_CACHE_HOME: " + xdg); }
}

fun isValidPath(s: String?): Boolean =
  s != null && runCatching { java.nio.file.Path.of(s) }.isSuccess

try { Path.of(System.getenv("XDG_CACHE_HOME")) } catch (e: InvalidPathException) { /* fall back to ~/.cache/pkl */ }

When it happens

Trigger: XDG_CACHE_HOME set in the environment to a value that is not a valid path on the current OS — e.g. containing NUL bytes or illegal characters on Windows, or shell-escaped garbage from misconfigured dotfiles.

Common situations: Windows users copying Unix-style env values, CI images exporting placeholder XDG values, typos in shell profiles exporting invalid cache directories.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• Failed to convert `pkl.base#String` to `java.nio.file.Path`.
• array
• Cannot convert Pkl duration `this` to `java.time.Duration`.
• Cannot convert Pkl object to Java object.%nPkl type
• Cannot convert ` ` to ` ` because no conversion was found.

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

Appendix: source

Thrown at pkl-executor/src/main/java/org/pkl/executor/ExecutorOptions.java:93

  public static Path defaultModuleCacheDir() {
    return defaultModuleCacheDir(
        Path.of(System.getProperty("user.home")), isWindowsOs(), System.getenv());
  }

  // Package-private; injectable so tests can exercise the Windows code path on a Unix CI box.
  static Path defaultModuleCacheDir(
      Path home, boolean isWindows, Map<String, String> environmentVariables) {
    // Keep in sync with org.pkl.core.util.IoUtils.getSystemModuleCacheDir (pkl-executor cannot
    // depend on pkl-core).
    //
    // On Unix prefer the XDG-style `~/.cache/pkl`.
    // On Windows prefer `%LOCALAPPDATA%/pkl/Cache`.
    var xdgConfig = environmentVariables.get("XDG_CACHE_HOME");
    if (xdgConfig != null && !xdgConfig.isEmpty()) {
      try {
        return Path.of(xdgConfig).resolve("pkl");
      } catch (InvalidPathException e) {
        logger.warn("'XDG_CACHE_HOME' is an invalid path: {}", e.getMessage());
      }
    }
    if (isWindows) {
      var localAppData = environmentVariables.get("LOCALAPPDATA");
      if (localAppData != null && !localAppData.isEmpty()) {
        try {
          return Path.of(localAppData).resolve("pkl/Cache");
        } catch (InvalidPathException e) {
          logger.warn("'LOCALAPPDATA' is an invalid path: {}", e.getMessage());
        }
      }
    }
    return home.resolve(".cache/pkl");
  }

  private static boolean isWindowsOs() {
    var osName = System.getProperty("os.name");
    return osName != null && osName.toLowerCase(Locale.ROOT).contains("windows");

View on GitHub (pinned to f3efcbfc9b)