{"record":{"id":"2a5be0eb4387d4dd","repo":"apple/pkl","slug":"xdg-cache-home-is-an-invalid-path","errorCode":null,"errorMessage":"'XDG_CACHE_HOME' is an invalid path: {}","messagePattern":"'XDG_CACHE_HOME' is an invalid path: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"pkl-executor/src/main/java/org/pkl/executor/ExecutorOptions.java","lineNumber":93,"sourceCode":"  public static Path defaultModuleCacheDir() {\n    return defaultModuleCacheDir(\n        Path.of(System.getProperty(\"user.home\")), isWindowsOs(), System.getenv());\n  }\n\n  // Package-private; injectable so tests can exercise the Windows code path on a Unix CI box.\n  static Path defaultModuleCacheDir(\n      Path home, boolean isWindows, Map<String, String> environmentVariables) {\n    // Keep in sync with org.pkl.core.util.IoUtils.getSystemModuleCacheDir (pkl-executor cannot\n    // depend on pkl-core).\n    //\n    // On Unix prefer the XDG-style `~/.cache/pkl`.\n    // On Windows prefer `%LOCALAPPDATA%/pkl/Cache`.\n    var xdgConfig = environmentVariables.get(\"XDG_CACHE_HOME\");\n    if (xdgConfig != null && !xdgConfig.isEmpty()) {\n      try {\n        return Path.of(xdgConfig).resolve(\"pkl\");\n      } catch (InvalidPathException e) {\n        logger.warn(\"'XDG_CACHE_HOME' is an invalid path: {}\", e.getMessage());\n      }\n    }\n    if (isWindows) {\n      var localAppData = environmentVariables.get(\"LOCALAPPDATA\");\n      if (localAppData != null && !localAppData.isEmpty()) {\n        try {\n          return Path.of(localAppData).resolve(\"pkl/Cache\");\n        } catch (InvalidPathException e) {\n          logger.warn(\"'LOCALAPPDATA' is an invalid path: {}\", e.getMessage());\n        }\n      }\n    }\n    return home.resolve(\".cache/pkl\");\n  }\n\n  private static boolean isWindowsOs() {\n    var osName = System.getProperty(\"os.name\");\n    return osName != null && osName.toLowerCase(Locale.ROOT).contains(\"windows\");","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-executor/src/main/java/org/pkl/executor/ExecutorOptions.java#L75-L111","documentation":"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).","triggerScenarios":"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.","commonSituations":"Windows users copying Unix-style env values, CI images exporting placeholder XDG values, typos in shell profiles exporting invalid cache directories.","solutions":["Fix XDG_CACHE_HOME to a valid absolute filesystem path (e.g. /home/user/.cache).","Unset XDG_CACHE_HOME so executor falls back to the platform default cache dir.","On Windows, remove characters invalid in NTFS paths from the value.","Check the warning log's cause message for which characters made the path invalid."],"exampleFix":"// before (shell profile)\nexport XDG_CACHE_HOME=\"$HOME/.cache/\"\n# after\nexport XDG_CACHE_HOME=\"$HOME/.cache\"","handlingStrategy":"validation","validationCode":"String xdg = System.getenv(\"XDG_CACHE_HOME\");\nif (xdg != null && !xdg.isEmpty()) {\n  try { java.nio.file.Path.of(xdg); } catch (InvalidPathException e) {\n    System.err.println(\"Invalid XDG_CACHE_HOME: \" + xdg); }\n}","typeGuard":"fun isValidPath(s: String?): Boolean =\n  s != null && runCatching { java.nio.file.Path.of(s) }.isSuccess","tryCatchPattern":"try { Path.of(System.getenv(\"XDG_CACHE_HOME\")) } catch (e: InvalidPathException) { /* fall back to ~/.cache/pkl */ }","preventionTips":["Validate XDG_CACHE_HOME after provisioning environments","Avoid OS-illegal characters (e.g. NUL, ':' on Windows) in env paths","Prefer unsetting the variable over setting a bogus value","Document cache-dir env requirements in project setup guides"],"tags":["env-var","cache","path","java"],"backgroundTag":"invalid-env-var-value","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}