FAQ and troubleshooting

The generated column is in the wrong position. Columns follow order in ascending order, not the declaration order. Check the order values, inherited columns included.

A field does not appear in the sheet. Only fields with @ExcelColumn are exported. Check that the annotation is on the field (or record component), that it is the sheetsmith annotation (cloud.baldilorenzo.sheetsmith.annotation.ExcelColumn) and that the SheetData uses the expected class.

My getter is not called. The getter must be public, non-static, without arguments, named getX (or isX for boolean/Boolean), and its return type must be assignable to the field type. A primitive/wrapper mismatch makes sheetsmith read the field directly (section 4.2.1).

Dates are shown as numbers. Excel stores dates as numbers; the format makes them look like dates. Built-in date values always get the default date format when no format is set. If a style or column sets a number format on a date column, that format wins. If the value was converted with CellValue.number, use CellValue.date or CellValue.dateTime instead.

My date format shows minutes instead of months (or the opposite). The format uses Excel syntax: mm is the month unless it follows an hour code or precedes a seconds code. Write dd/mm/yyyy for dates and hh:mm for times.

Numbers show too many decimals. Set a format on the column, on a style or as sheetsmith.formats.number. float fields show binary artefacts: prefer double or BigDecimal.

Leading zeros disappear. The value is numeric. Keep it as String or convert it with CellValue.text.

The application fails at startup with “both handle type”. Two converter beans handle the same type. Keep one, or turn the column-specific one into a field converter that is not a bean (section 9.8).

All my string columns are transformed by a converter I wrote for one column. The converter handles String and is a Spring bean, so it is an application converter for every String column. Remove the bean annotation and declare it with @ExcelColumn(converter = ...).

V-10 in tests but not in production. The test generator lacks the application converters. Validate with a generator configured like production, or inject the Spring bean.

V-17 in a modular application. Open the package of the sheet class: opens com.example.export; works whether sheetsmith is on the module path or the class path.

The preset has no effect. Check the effective preset: @ExcelSheet.preset must be LIGHT, MEDIUM or DARK, or INHERIT with an application default other than NONE. Remember that every declared style overrides the preset: a body.base with a fillColor hides the zebra.

My accentColor is ignored. It is used only when the effective preset is not NONE.

The YAML accent colour is ignored or the application fails to start. Quote values starting with # in YAML: accent-color: "#1F4E79".

Columns are too narrow or too wide on the server, but fine on my machine. The server lacks fonts and the width falls back to an estimate. Install fonts in the image, or set explicit widths (section 12.4).

The single column of a titled sheet is as wide as the title. Known behaviour (section 12.4): set an explicit width.

Excel says the file needs repair. The usual causes are an invalid data format code (formats are not validated) or a sheet named History.

The generation is slow or runs out of memory. See section 12.3: disable automatic sizing, set widths, size the heap, limit concurrency.

Can I write formulas, images, comments, conditional formatting or data validation? Not in version 1.0.0. A text starting with = is written as text, not as a formula.

Can I translate headers? Headers are written as declared. Localisation is left to the application, for example by preparing different sheet classes or by post-processing.

Can I use sheetsmith outside Spring? Yes: import sheetsmith-core and use Sheetsmith.builder().

Can I use the classes in cloud.baldilorenzo.sheetsmith.internal? No. They are implementation details, excluded from the published Javadoc and subject to change without notice (Appendix A).