Exceptions

RuntimeException
 └── SheetsmithException                    (sealed, abstract)
      ├── SheetsmithConfigurationException  (final)
      └── SheetsmithGenerationException     (final)

All library exceptions are unchecked and serialisable. There are two kinds, which call for different reactions:

Exception	Meaning	When	Typical reaction
SheetsmithConfigurationException	A sheet class or the input is wrong: a programming error.	Before anything is written: in generate, in validate, at startup validation.	Fix the code. Catch it early with validate in tests or at startup.
SheetsmithGenerationException	Something went wrong while writing the data: usually unexpected data at runtime.	During the writing of a sheet.	Log it with sheet, row and field; fix the data or the converter.

A failure while the workbook is serialised is neither: it is an infrastructure error, reported as a java.io.UncheckedIOException and deliberately not wrapped in a sheetsmith exception, so that callers can handle it apart from configuration and data errors.

SheetsmithConfigurationException

Member	Description
SheetsmithConfigurationException(List<ConfigurationError> errors)	Public constructor; errors not null and not empty (IllegalArgumentException if empty).
List<ConfigurationError> errors()	The errors, in the order they were found; unmodifiable, never empty, preserved by Java serialisation.
getMessage()	One line per error, in the format described in section 11.1.

SheetsmithGenerationException

Member	Description
SheetsmithGenerationException(String message, String sheetName, int rowIndex, String fieldName, Throwable cause)	Public constructor. rowIndex 0 when not specific to a row (negative values throw IllegalArgumentException); fieldName and cause may be null. The message is completed with the location.
String sheetName()	The name of the sheet being written.
int rowIndex()	The 1-based data row, in list order (row 1 is the first element); 0 when the error is not specific to a row, such as too many rows. Title and header are not counted.
Optional<String> fieldName()	The field involved, as declared in the sheet class; empty when not specific to a field, such as a null element.
getCause()	The original exception thrown by a getter or a converter, when there is one.

ConfigurationError

public record ConfigurationError(String code, Class<?> type, String element, String message) implements Serializable

Component	Meaning
code	The violated rule, from V-01 to V-20.
type	The class the error refers to: the sheet class, or the style sheet that declares the faulty style; null for errors on the input of generate (V-18 to V-20).
element	The element involved: a field name, @ExcelSheet, @ExcelStyle(name), @ExcelStyle(#n) when the name is blank, sheets[i] for a sheet of the input; empty when the error concerns the class or the input as a whole.
message	The description of the problem.

code, element and message are not null (NullPointerException otherwise).