# Troubleshooting

Start with `report.hasError()` / `report.lastErrorMsg()` after the run, and the application's debug output.

## Compile and link errors

| Symptom | Cause and fix |
| --- | --- |
| `runReportToPreview` / `runReportToModernPreview` is not a member of `NCReport` | `NCR_PREVIEW_MODULE` is not defined in the application. Add `<build>/include` (holds `ncreport_config.h`) to the include path, or `DEFINES += NCR_PREVIEW_MODULE` |
| `ncreportpreviewwindow.h: No such file` | Add `src/ncreport/preview` to the include path (installed headers are in one folder) |
| `runReportToPDF` is not a member | The method is `runReportToPdfWriter()` (or `runReportToPdf()`) |
| `no matching function for runReportToModernPreview()` | It has no default arguments: `runReportToModernPreview(0, QString(), parent)` |
| `cannot find -lNCReport` in a debug build | Debug libraries are `NCReportd` (Linux, macOS) and `NCReportd2` (Windows) |
| `cannot find -lNCReportDebug2` | Name from releases before 2.27; use `NCReportd2` / `NCReportd` |
| Unresolved `__imp_…NCReport…` on Windows | Compiler or debug/release mismatch between the application and the library (MSVC vs MinGW, Qt version) |
| Unresolved Zint symbols | Link Zint too: `-lzint` / `-lzint2` (`zintd` / `zintd2` for debug) |
| `Unknown module(s) in QT: script` (Qt 5 source build) | Install Qt Script, or build with `DISABLED_FEATURES += script` |

## Runtime errors

| Symptom | Cause and fix |
| --- | --- |
| `libzint.so.2: cannot open shared object file` | Ship `libzint` next to `libNCReport`, and give the application an rpath or `LD_LIBRARY_PATH` |
| macOS `Library not loaded: @rpath/NCReport.framework` | Copy the framework into `Contents/Frameworks` and add the rpath `@executable_path/../Frameworks` |
| `Could not load database driver` | The Qt SQL driver plugin (`sqldrivers/`) or its client library (libpq, libmysql, OCI) is missing from the deployment |
| `Database connection ID … is already used` | The template uses `connection="external"` with a name the application already opened; use `connection="internal"` |
| `Item model not found. Data source ID: x Model ID: y` | `addItemModel(model, "y")` was not called before the run, or the id differs from the template's `modelID` |
| `Invalid datasource type` | The template's `<datasource type>` is not one of `sql txt xml list model custom` |
| `Uncompatible NCReport file version` | The root `version` attribute is missing or below 2.0 |
| A crash at exit or when closing the preview | The output was deleted twice (the preview window owns it), or the `NCReport` object died while its preview was open |
| Crash or nothing happens without a window | No `QApplication`; the engine needs one even for PDF |
| Printing or `runReportToPdf()` does nothing on Android | No QPrinter there: use `runReportToPdfWriter()` |

## Wrong output

| Symptom | Cause and fix |
| --- | --- |
| `#DATA#`, `#PARAM#` or `#VAR#` printed | Unknown column, parameter or variable name (all case-sensitive). Parameters must be added before the run |
| A field is empty, an attribute "does nothing" | Typo in an element or attribute name: the reader ignores unknown names. Compare with a Designer-made template |
| Detail items missing | Items directly under `<detail>`: wrap them in `<items>` |
| Group never breaks | `groupExp="$D{col}"`: write the bare column `groupExp="col"`. Or the data is not sorted by the group column |
| Group total never resets | The variable is not listed in the group's `resetVariables` |
| Grand total in the report footer is wrong | It uses a `group` scope variable; use `scope="report"` |
| `$V{pagecount}` is 0 | Turn on `<doublePass>true</doublePass>` (not `1`), and make sure the template has a `<pagefooter>` section (an empty one is enough): pages are counted when the page footer is processed |
| A custom data source prints empty fields | Implement `columnCount()` and `columnName(int)`: the engine looks columns up with `columnIndexByName()` before calling `value()` |
| Script compares strings wrongly | References are substituted as text: quote them, `"$D{status}" == "paid"` |
| Script in an attribute breaks the XML | Escape it: `&lt;% … %&gt;`, `&gt;`, `&amp;` |
| A landscape page prints as portrait | `<orientation>` must come before `<pagesize>` in `<options>` |
| "EVALUATION VERSION" on every page | The evaluation build; the licensed packages and source builds do not print it |
| Fonts differ between machines | The font in the template (`fontname`, `fontName`) is not installed; register one with `QFontDatabase::addApplicationFont()` or use a font the target has |
| Barcode is empty | The engine was built without the `barcode` extension, or the value is not valid for the symbology |
| Text item cut at the page end | Needs `canBreak` and `autoHeight` on the item, `autoHeight` on the section and `<zoneBreak>true</zoneBreak>` |
