{"record":{"id":"23a269eecb02335a","repo":"apple/pkl","slug":"maps-with-non-string-keys-cannot-currently-be-rend","errorCode":null,"errorMessage":"Maps with non-String keys cannot currently be rendered as YAML. Key: %s","messagePattern":"Maps with non-String keys cannot currently be rendered as YAML\\. Key: (.+?)","errorType":"exception","errorClass":"RendererException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/YamlRenderer.java","lineNumber":179,"sourceCode":"      doVisitIterable(value, null);\n    }\n\n    @Override\n    public void visitList(List<?> value) {\n      doVisitIterable(value, null);\n    }\n\n    @Override\n    public void visitSet(Set<?> value) {\n      doVisitIterable(value, \"!!set\");\n    }\n\n    @Override\n    public void visitMap(Map<?, ?> value) {\n      for (var key : value.keySet()) {\n        if (!(key instanceof String)) {\n          // http://stackoverflow.com/questions/33987316/what-is-a-complex-mapping-key-in-yaml\n          throw new RendererException(\n              String.format(\n                  \"Maps with non-String keys cannot currently be rendered as YAML. Key: %s\", key));\n        }\n      }\n\n      @SuppressWarnings(\"unchecked\")\n      var mapValue = (Map<String, ?>) value;\n      doVisitProperties(mapValue);\n    }\n\n    @Override\n    public void visitObject(PObject value) {\n      doVisitProperties(value.getProperties());\n    }\n\n    @Override\n    public void visitModule(PModule value) {\n      doVisitProperties(value.getProperties());","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/YamlRenderer.java#L161-L197","documentation":"YAML mapping keys here are restricted to strings; complex mapping keys (numbers, booleans, nested collections) are not supported by the renderer. visitMap pre-scans keys and throws RendererException on the first non-String key.","triggerScenarios":"renderDocument on a Map (or Pkl Mapping) with non-String keys such as Map(1, \"a\") or Map(true, ...) — the key scan in visitMap fails.","commonSituations":"Pkl objects using Int/Boolean keys (e.g. port-number keyed maps) exported to YAML; generic Map built programmatically with Integer keys; JSON-to-YAML pipelines where parsed numeric keys survived.","solutions":["Convert non-String keys to strings before rendering: Map(\"1\", value) or keys.toString().","Restructure the data as a List of {key, value} objects instead of a keyed map.","Fix the Pkl module to use String keys (e.g. quote the keys) if the source is Pkl code."],"exampleFix":"// before\nrenderer.renderDocument(Map(8080, \"http\")); // throws\n// after\nrenderer.renderDocument(Map(\"8080\", \"http\"));","handlingStrategy":"validation","validationCode":"void requireStringKeys(Map<?, ?> m) {\n  for (var k : m.keySet()) {\n    if (!(k instanceof String)) throw new IllegalArgumentException(\"non-String key: \" + k);\n  }\n}","typeGuard":"boolean hasOnlyStringKeys(Map<?, ?> m) { return m.keySet().stream().allMatch(String.class::isInstance); }","tryCatchPattern":"try {\n  renderer.renderDocument(map);\n} catch (RendererException e) {\n  if (e.getMessage().contains(\"Maps with non-String keys\")) {\n    renderer.renderDocument(stringKeyify(map)); // keys -> String.valueOf(k)\n  } else throw e;\n}","preventionTips":["Use String keys in Pkl mappings intended for YAML output (quote numeric keys).","Model keyed collections as lists of {key, value} entries when keys are non-string.","Validate map key types before handing data to the renderer."],"tags":["yaml","rendering","map-keys","pkl","unsupported"],"backgroundTag":"unsupported-operation","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"}