{"record":{"id":"cefb86025c2677e0","repo":"apache/iceberg","slug":"invalid-default-value-for-s-s-must-be-null","errorCode":null,"errorMessage":"Invalid default value for %s: %s (must be null)","messagePattern":"Invalid default value for (.+?): (.+?) \\(must be null\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"api/src/main/java/org/apache/iceberg/types/Types.java","lineNumber":897,"sourceCode":"        Literal<?> writeDefault) {\n      Preconditions.checkNotNull(name, \"Name cannot be null\");\n      Preconditions.checkNotNull(type, \"Type cannot be null\");\n      Preconditions.checkArgument(\n          isOptional || !type.equals(UnknownType.get()),\n          \"Cannot create required field with unknown type: %s\",\n          name);\n      this.isOptional = isOptional;\n      this.id = id;\n      this.name = name;\n      this.type = type;\n      this.doc = doc;\n      this.initialDefault = castDefault(initialDefault, type);\n      this.writeDefault = castDefault(writeDefault, type);\n    }\n\n    private static Literal<?> castDefault(Literal<?> defaultValue, Type type) {\n      if (type.isNestedType() && defaultValue != null) {\n        throw new IllegalArgumentException(\n            String.format(\"Invalid default value for %s: %s (must be null)\", type, defaultValue));\n      } else if (defaultValue != null) {\n        Literal<?> typedDefault = defaultValue.to(type);\n        Preconditions.checkArgument(\n            typedDefault != null, \"Cannot cast default value to %s: %s\", type, defaultValue);\n        return typedDefault;\n      }\n\n      return null;\n    }\n\n    public boolean isOptional() {\n      return isOptional;\n    }\n\n    public NestedField asOptional() {\n      if (isOptional) {\n        return this;","sourceCodeStart":879,"sourceCodeEnd":915,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/types/Types.java#L879-L915","documentation":"Thrown by Types.NestedField's castDefault when a non-null initialDefault or writeDefault is supplied for a nested-typed field (struct, list, map, variant). Defaults for nested types must be null; only primitive-typed fields accept non-null literal defaults.","triggerScenarios":"Building a NestedField with Types.NestedField.required/optional(...).withInitialDefault(someLiteral) (or withWriteDefault) where the field's type is a nested type and the literal is non-null.","commonSituations":"Programmatic schema builders that blanket-apply defaults to all fields; schema evolution code copying defaults from a primitive field template to nested fields; DDL translation where source engines allow nested defaults but Iceberg does not.","solutions":["Pass null (or omit withInitialDefault/withWriteDefault) for fields whose type is nested","Only set literal defaults when the field type is a primitive type","Add a check in schema-building code: if (fieldType.isNestedType()) skip setting the default"],"exampleFix":"// before\nTypes.NestedField.optional(1, \"items\", Types.ListType.ofOptional(2, Types.StringType.get()))\n    .withInitialDefault(literal(\"x\"))\n// after\nTypes.NestedField.optional(1, \"items\", Types.ListType.ofOptional(2, Types.StringType.get()))","handlingStrategy":"validation","validationCode":"if (fieldType.isNestedType() && initialDefault != null) {\n  throw new IllegalArgumentException(\"Defaults must be null for nested type: \" + fieldType);\n}","typeGuard":null,"tryCatchPattern":"try {\n  builder.withInitialDefault(literal);\n} catch (IllegalArgumentException e) {\n  // nested type: retry without a default\n}","preventionTips":["Only set field defaults when Types.NestedField.type().isPrimitiveType() is true","Guard schema builders with a nested-type check before applying defaults","Keep default-value application in one utility so the guard is enforced everywhere"],"tags":["java","schema","nested-types","default-value"],"backgroundTag":"invalid-argument-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}