Error codes

Each entry gives the rule, the element reported, a minimal example that triggers it, the message and the fix.

V-01: the class is annotated with @ExcelSheet

• Element: none.
• Example: SheetData.of("Rows", PlainRecord.class, rows) where PlainRecord has no @ExcelSheet; or @ExcelSheet placed only on a superclass.
• Message: [V-01] com.example.PlainRecord: the class is not annotated with @ExcelSheet
• Fix: annotate the class passed to SheetData. The annotation is not inherited.

V-02: the class has at least one @ExcelColumn field

• Element: none.
• Example: @ExcelSheet public record Empty(String name) { }
• Message: [V-02] com.example.Empty: no field is annotated with @ExcelColumn
• Fix: annotate at least one field. Remember that export is opt-in.

V-03: order values are unique

• Element: the field found second.
• Example: two columns with order = 10, code and name.
• Message: [V-03] com.example.Row.name: order 10 is also used by field code
• Fix: give each column a different order. Inherited columns count.

V-04: header is not blank

• Element: the field.
• Example: @ExcelColumn(header = " ", order = 10) String code;
• Message: [V-04] com.example.Row.code: header is blank
• Fix: set a header text.

V-05: @ExcelColumn is not on a static field

• Element: the field.
• Example: @ExcelColumn(header = "Total", order = 99) static int TOTAL;
• Message: [V-05] com.example.Row.TOTAL: @ExcelColumn is not allowed on a static field
• Fix: move the annotation to an instance field.

V-06: every referenced style exists

• Element: the field for headerStyle and column slots; @ExcelSheet for titleStyle, header and body slots.
• Example: body = @BodyStyles(lastRow = "totals") when the style is named total.
• Message: [V-06] com.example.Row.@ExcelSheet: style 'totals' not found (referenced by body.lastRow)
• Slot names in the message: titleStyle, header.base, header.firstColumn, header.lastColumn, body.base, body.odd, body.even, body.firstRow, body.lastRow, body.firstColumn, body.lastColumn, headerStyle, styles.base, styles.odd, styles.even, styles.firstRow, styles.lastRow.
• Fix: declare the style, reference the style sheet that declares it, or fix the name. Names are case-sensitive and matched exactly.

V-07: style names are unique within one declaring class

• Element: @ExcelStyle(name); the class is the sheet class or the style sheet that declares the duplicate.
• Example: @ExcelStyle(name = "header", bold = Toggle.TRUE) twice on the same class.
• Message: [V-07] com.example.CorporateStyles.@ExcelStyle(header): style 'header' is declared more than once
• Fix: rename or merge the duplicates. A style on the sheet class with the same name as a style of a style sheet is not a duplicate: it is an intentional override.

V-08: the style sheets of one class do not define the same name

• Element: @ExcelSheet of the sheet class.
• Example: styleSheets = {CorporateStyles.class, FinanceStyles.class}, both declaring money.
• Message: [V-08] com.example.Row.@ExcelSheet: styleSheets: style 'money' is defined by both com.example.CorporateStyles and com.example.FinanceStyles
• Fix: rename the style in one style sheet, or redefine it on the sheet class.

V-09: every class in styleSheets has @ExcelStyleSheet

• Element: @ExcelSheet of the sheet class.
• Example: styleSheets = CorporateStyles.class without @ExcelStyleSheet on CorporateStyles.
• Message: [V-09] com.example.Row.@ExcelSheet: styleSheets: com.example.CorporateStyles is not annotated with @ExcelStyleSheet
• Fix: annotate the style sheet. Expect V-06 errors for its styles in the same report, since they are not loaded.

V-10: a converter exists for the column type, and the resolution is not ambiguous

• Element: the field.
• Example (missing): @ExcelColumn(header = "Id", order = 10) UUID id; without a converter.
• Message: [V-10] com.example.Row.id: no converter for type java.util.UUID: declare one with @ExcelColumn(converter = ...) or register one for the type
• Example (ambiguous): a field type implementing two interfaces that both have an application converter, at the same distance.
• Message: [V-10] com.example.Row.code: converter for type com.example.Code is ambiguous: candidates [com.example.Labelled, com.example.Coded]: declare one with @ExcelColumn(converter = ...) or register one for the exact type
• Fix: declare a field converter, or register an application converter for the type (for the exact type in the ambiguous case). Validate with a generator configured like the production one.

V-11: the field converter handles a compatible type

• Element: the field.
• Example: @ExcelColumn(header = "Qty", order = 20, converter = UuidAsText.class) int quantity;
• Message: [V-11] com.example.Row.quantity: converter com.example.UuidAsText handles java.util.UUID, which is not assignable from the field type int
• Fix: use a converter whose handled type is the field type or one of its supertypes (primitives count as their wrappers).

V-12: the field converter can be created

• Element: the field.
• Examples and messages:
  • no public no-argument constructor: [V-12] com.example.Row.amount: converter com.example.MoneyConverter cannot be created: com.example.MoneyConverter has no public no-argument constructor
  • constructor that throws: ... cannot be created: constructor of com.example.MoneyConverter failed: java.lang.IllegalStateException: ...
  • class not public, abstract, or otherwise not instantiable: ... cannot be created: cannot instantiate com.example.MoneyConverter: ...
  • custom factory that returns null: ... cannot be created: the converter factory returned null
  • Spring factory unable to create it (missing dependency, for example): the message of the Spring exception.
• Fix: make the converter a public class (public static if nested) with a public no-argument constructor, or configure a factory that can create it, such as the Spring Boot one.

V-13: colours have a valid syntax

• Element: @ExcelStyle(name) for style colours; @ExcelSheet for accentColor and outerBorderColor.
• Example: fillColor = "#1F4E7", fontColor = "dark_blue", accentColor = "blue".
• Message: [V-13] com.example.Row.@ExcelStyle(header): fillColor '#1F4E7' is not a valid colour: expected #RRGGBB or the name of an IndexedColors constant
• Fix: use #RRGGBB with six hexadecimal digits, or an IndexedColors name in upper case.

V-14: numeric attributes are in range

• Element: @ExcelStyle(name) for style attributes; the field for width.
• Ranges and messages:
  • rotation -90 to 90 or 255: rotation 120 is out of range -90 to 90, or 255
  • indent 0 to 250: indent 300 is out of range 0 to 250
  • fontSize 1 to 409: fontSize 0 is out of range 1 to 409
  • width 1 to 255: [V-14] com.example.Row.description: width 300 is out of range 1 to 255
• Fix: use a value in range. ExcelStyle.UNSET is always accepted.

V-15: titleStyle only with title

• Element: @ExcelSheet.
• Example: @ExcelSheet(titleStyle = "title") without title.
• Message: [V-15] com.example.Row.@ExcelSheet: titleStyle is set but title is empty
• Fix: set a title, or remove the title style.

V-16: style names are not blank

• Element: @ExcelStyle(#n), n being the 1-based position of the declaration on its class.
• Example: @ExcelStyle(name = "", bold = Toggle.TRUE) as the second style of the class.
• Message: [V-16] com.example.Row.@ExcelStyle(#2): style name is blank
• Fix: name the style.

V-17: every column value is accessible

• Element: the field.
• Example: a sheet class in a named module whose package is not open, read through a private field.
• Message: [V-17] com.example.export.Row.amount: value is not accessible (<reason>); add a public getter or open package com.example.export to sheetsmith, for example with 'opens com.example.export;' in module-info.java
• Fix: add a public getter with a compatible return type, or open the package (section 4.2.1).

V-18: the sheet list is not empty

• Element: none; no class.
• Example: sheetsmith.generate(List.of()).
• Message: [V-18] the sheet list is empty
• Fix: pass at least one sheet. An empty data list for a sheet is valid; an empty list of sheets is not.

V-19: sheet names are valid

• Element: sheets[i]; no class.
• Messages:
  • length: [V-19] sheets[0]: sheet name '' must be 1 to 31 characters long (it has 0)
  • characters: [V-19] sheets[2]: sheet name 'Q3/2026' must not contain any of \ / ? * [ ] :
  • apostrophe: [V-19] sheets[1]: sheet name ''Draft'' must not start or end with '
• Fix: choose a valid name. sheetsmith never shortens or cleans names.

V-20: sheet names are unique, ignoring case

• Element: sheets[i] of the later duplicate; no class.
• Example: sheets named Summary and SUMMARY.
• Message: [V-20] sheets[3]: sheet name 'SUMMARY' is already used by sheets[0] 'Summary', ignoring case
• Fix: rename one of the sheets.