{"record":{"id":"1cb24cb3f3100f45","repo":"apple/pkl","slug":"invalidrelativeprojectimport","errorCode":"invalidRelativeProjectImport","errorMessage":"invalidRelativeProjectImport","messagePattern":"invalidRelativeProjectImport","errorType":"error_code","errorClass":"PklException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/project/ProjectPackager.java","lineNumber":451,"sourceCode":"    var imports = getImportsAndReads(pklModulePath);\n    for (var importContext : imports) {\n      var importStr = importContext.stringValue();\n      var sourceSection = importContext.sourceSection();\n      if (isAbsoluteImport(importStr)) {\n        continue;\n      }\n      URI importUri;\n      try {\n        importUri = IoUtils.toUri(importStr);\n      } catch (URISyntaxException e) {\n        throw new VmExceptionBuilder()\n            .evalError(\"invalidModuleUri\", importStr)\n            .withSourceSection(sourceSection)\n            .build()\n            .toPklException(stackFrameTransformer, color);\n      }\n      if (importStr.startsWith(\"/\") && !project.getProjectDir().toString().equals(\"/\")) {\n        throw new VmExceptionBuilder()\n            .evalError(\"invalidRelativeProjectImport\", importStr)\n            .withSourceSection(sourceSection)\n            .build()\n            .toPklException(stackFrameTransformer, color);\n      }\n      var currentPath = pklModulePath.getParent();\n      assert currentPath != null;\n      var importPath = importUri.getPath().split(\"/\");\n      // It's not good enough to just check the normalized path to see whether it exists within the\n      // root dir.\n      // It's possible that the import path resolves to a path outside the project dir,\n      // and then back inside the project dir.\n      for (var segment : importPath) {\n        // replace any possibly reserved filename characters with underscore.\n        currentPath = currentPath.resolve(sanitizePathSegment(segment));\n        var normalized = currentPath.normalize();\n        if (!normalized.startsWith(project.getProjectDir())) {\n          throw new VmExceptionBuilder()","sourceCodeStart":433,"sourceCodeEnd":469,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/project/ProjectPackager.java#L433-L469","documentation":"Raised when a module imports a path starting with `/` (an absolute path) while the project's directory is not the filesystem root. Package validation forbids absolute-path imports because they cannot be resolved relative to the packaged project.","triggerScenarios":"validateImportsAndReads sees an importStr beginning with \"/\" and project.getProjectDir() != \"/\" during `pkl project package` validation.","commonSituations":"Accidentally writing import \"/foo/bar.pkl\" instead of a relative path; copy-pasted absolute paths from local experiments into project sources.","solutions":["Change the import to a project-relative path (e.g. import \"foo/bar.pkl\")","Remove the leading slash from the import string","If an external file is truly needed, declare it as a dependency instead"],"exampleFix":"// before\nimport \"/shared/base.pkl\"\n// after\nimport \"../shared/base.pkl\"  // or a project-relative path","handlingStrategy":"validation","validationCode":"// reject absolute import paths before packaging\nif (importStr.startsWith(\"/\")) throw new IllegalStateException(\"absolute import not allowed: \" + importStr);","typeGuard":null,"tryCatchPattern":"try { validatePklImportsAndReads(...) } catch (PklException e) { if (e.message.contains(\"invalidRelativeProjectImport\")) showRelativeImportGuidance(e) else throw e }","preventionTips":["Always write project-relative import paths","Never copy absolute paths from scratch files into project sources","Review import statements in code review for leading slashes"],"tags":["import","path","validation"],"backgroundTag":"invalid-url-format","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}