{"record":{"id":"f0cc34ef5562e161","repo":"apple/pkl","slug":"cannotiterateoverthisvalue-f0cc34","errorCode":"cannotIterateOverThisValue","errorMessage":"Cannot iterate over value of type `{0}`.","messagePattern":"Cannot iterate over value of type `(.+?)`\\.","errorType":"exception","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/expression/generator/GeneratorSpreadNode.java","lineNumber":74,"sourceCode":"    this.nullable = nullable;\n  }\n\n  protected abstract void executeWithIterable(\n      VirtualFrame frame, Object parent, ObjectData data, Object iterable);\n\n  @Override\n  public final void execute(VirtualFrame frame, Object parent, ObjectData data) {\n    executeWithIterable(frame, parent, data, iterableNode.executeGeneric(frame));\n  }\n\n  @Specialization\n  @SuppressWarnings(\"unused\")\n  protected void eval(VmObject parent, ObjectData data, VmNull iterable) {\n    if (nullable) {\n      return;\n    }\n    CompilerDirectives.transferToInterpreter();\n    throw exceptionBuilder()\n        .evalError(\"cannotIterateOverThisValue\", BaseModule.getNullClass())\n        .withLocation(iterableNode)\n        .withHint(\n            \"To guard against a nullable value, use `...?` instead of `...`.\\n\"\n                + \"Try: `...?\"\n                + iterableNode.getSourceSection().getCharacters()\n                + \"`\")\n        .build();\n  }\n\n  @Specialization(guards = \"!iterable.isTyped()\")\n  @SuppressWarnings(\"unused\")\n  protected void eval(VirtualFrame frame, VmDynamic parent, ObjectData data, VmObject iterable) {\n    doEvalDynamic(frame, data, iterable);\n  }\n\n  @Specialization(guards = \"!iterable.isTyped()\")\n  @SuppressWarnings(\"unused\")","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/expression/generator/GeneratorSpreadNode.java#L56-L92","documentation":"Pkl's `...` spread operator was applied to a value that evaluated to `null`, so the generator cannot iterate it. Pkl throws this instead of silently skipping the spread. The error suggests using `...?` (nullable spread) which skips null values.","triggerScenarios":"Using `...expr` inside an object literal where `expr` evaluates to `null` (e.g. a property that is null, an external value, or a conditional that produced nothing).","commonSituations":"Config files where an optional external input (env var, CLI argument, imported property) is null and is spread into a Dynamic/Listing: `...options` where `options = null`.","solutions":["Use the nullable spread operator `...?` instead of `...` to skip null values.","Guard the value before spreading: `...(options ?? [])`.","Fix the upstream expression so it returns an empty List/Map instead of null."],"exampleFix":"// before\nfoo {\n  ...maybeNullList\n}\n// after\nfoo {\n  ...?maybeNullList\n}","handlingStrategy":"type-guard","validationCode":"if (maybeNull != null) { /* safe to spread */ }","typeGuard":"function isSpreadable(v) { return v != null && (v is List || v is Map || v is Set || v is IntSeq); }","tryCatchPattern":"Use `...?expr` so null is skipped rather than thrown.","preventionTips":["Prefer `...?` whenever the spread operand may be null.","Normalize optional inputs with `?? []` before spreading.","Give optional properties non-null default values (empty List/Map)."],"tags":["pkl","spread-operator","null-value"],"backgroundTag":"null-argument","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"}