{"record":{"id":"3a16126102758fff","repo":"apple/pkl","slug":"wrongheaders-3a1612","errorCode":"wrongHeaders","errorMessage":"{0} cannot have doc comments, annotations or modifiers.","messagePattern":"(.+?) cannot have doc comments, annotations or modifiers\\.","errorType":"exception","errorClass":"GenericParserError","httpStatus":null,"severity":"error","filePath":"pkl-parser/src/main/java/org/pkl/parser/GenericParserImpl.java","lineNumber":74,"sourceCode":"    if (lookahead == Token.SHEBANG) {\n      nodes.add(makeAffix(next()));\n    }\n    ff(nodes);\n\n    var res = parseMemberHeader(children);\n\n    if (isModuleDecl()) {\n      nodes.add(parseModuleDecl(children));\n      children.clear();\n      res = new HeaderResult(false, false, false);\n      ff(nodes);\n    }\n\n    // imports\n    var imports = new ArrayList<Node>();\n    while (lookahead == Token.IMPORT || lookahead == Token.IMPORT_STAR) {\n      if (res.hasDocComment || res.hasAnnotations || res.hasModifiers) {\n        throw parserError(\"wrongHeaders\", \"Imports\");\n      }\n      var lastImport = parseImportDecl();\n      imports.add(lastImport);\n      // keep trailing affixes as part of the import\n      while (lookahead.isAffix() && lastImport.span.isSameLine(spanLookahead)) {\n        imports.add(makeAffix(next()));\n      }\n      if (!isImport()) break;\n      ff(imports);\n    }\n    if (!imports.isEmpty()) {\n      nodes.add(new Node(NodeType.IMPORT_LIST, imports));\n      ff(nodes);\n    }\n\n    // entries\n    if (res.hasDocComment || res.hasAnnotations || res.hasModifiers) {\n      nodes.add(parseModuleMember(children));","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-parser/src/main/java/org/pkl/parser/GenericParserImpl.java#L56-L92","documentation":"Pkl's module parser rejects doc comments, annotations, or modifiers appearing between the module header clauses and the imports section. Imports must come directly after the module/amends/extends headers, before anything else; parserError(\"wrongHeaders\", \"Imports\") fires when res already accumulated a doc comment, annotations, or modifiers by the time an import token is seen.","triggerScenarios":"A .pkl module declares a doc comment (///), annotations (@...), or modifiers (e.g. `open`, `abstract`) and THEN writes `import ...` statements, e.g. `module x\\n@Deprecated\\nimport \"a\"` or `open module m\\n/// doc\\nimport \"b\"`.","commonSituations":"Reordering statements while refactoring (moving imports above/below annotations); auto-formatters or code generators emitting imports after annotations; developers assuming import placement is free-form like in Java.","solutions":["Move all import statements to immediately after the module/amends/extends header, before any doc comment, annotation, or modifier lines.","Attach the doc comment/annotations to the actual declaration they document (a class, property, or the module itself) rather than leaving them above imports.","Remove modifiers that aren't valid on imports; imports accept no modifiers in Pkl."],"exampleFix":"// before\n@Deprecated\nimport \"lib.pkl\"\nmodule my.mod\n// after\nmodule my.mod\nimport \"lib.pkl\"\n\n@Deprecated\nfoo { ... }","handlingStrategy":"validation","validationCode":"// lint rule: imports must appear before any doc comment/annotation/modifier line after the header\nconst bad = /(\\/\\/\\/|@[A-Za-z_]|\\b(open|abstract|sealed|hidden)\\b)[^\\n]*\\n\\s*(import\\s)/;\nif (bad.test(pklSource)) throw new Error(\"Move imports above doc comments/annotations/modifiers\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Adopt a fixed module layout: headers, then imports, then declarations.","Configure your formatter/linter to enforce import placement in .pkl files.","Don't attach doc comments or annotations to import statements — they aren't documentable."],"tags":["pkl","parser","syntax"],"backgroundTag":"invalid-syntax","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"}