Skip to content

Troubleshooting

Jump to bottom
Peter Gill edited this page Jun 8, 2026 · 1 revision

Troubleshooting

Common issues and their fixes, grouped by symptom.

Report generates no output / blank PDF

Check 1 — ErrorMaxSeverity

Always check for errors after Parse() and after RunGetData(). A severity > 4 means the engine stopped processing.

using var report = await rdlp.Parse();
if (report.ErrorMaxSeverity > 4)
{
    foreach (string msg in report.ErrorItems)
        Console.WriteLine(msg);
    return; // do not call RunGetData or RunRender
}

See Error Handling for the full pattern.

Check 2 — RdlEngineConfigInit not called

RdlEngineConfig.RdlEngineConfigInit() must be called once before any report is parsed. If it is never called, data providers are not registered and the engine silently produces no output.

Check 3 — empty dataset

If the SQL query returns zero rows the report body renders with no detail rows. Verify the query independently against your database.

Report shows no data / detail rows are missing

  • The dataset query returns zero rows — test the SQL directly.
  • Parameters passed to RunGetData don't match the parameter names declared in the report (names are case-sensitive). See Report Parameters.
  • The connection string is wrong or the database is unreachable — check ErrorItems for a connection error message.
  • The report's dataset filter is excluding all rows — check any filters defined on the dataset in the designer.

Wrong or missing fonts in PDF output on Linux

SkiaSharp falls back to a default font when the font specified in the report is not installed on the system. Symptoms: text renders in a different typeface or character glyphs are replaced with boxes.

Fix: install the required fonts and rebuild the font cache.

# Debian / Ubuntu
sudo apt-get install fonts-liberation fontconfig
sudo fc-cache -fv

# Verify the font is found
fc-list | grep -i "arial\|liberation"

See Linux — Fonts and SkiaSharp setup and Docker Deployment for full font setup instructions.

DllNotFoundException: libSkiaSharp

The SkiaSharp native binary is missing or the wrong variant is installed.

  • On Linux/macOS, install the .SkiaSharp NuGet packages (Majorsilence.Reporting.RdlEngine.SkiaSharp), not the default Windows packages.
  • On Alpine Linux, ensure the linux-musl-x64 runtime identifier is targeted and native Alpine packages (fontconfig, freetype, harfbuzz) are installed.
  • Verify the RID in your .csproj: <RuntimeIdentifier>linux-x64</RuntimeIdentifier> (or linux-musl-x64 for Alpine).

Parameter not applied / wrong data with parameters

  • Parameter names passed in code must exactly match the <Name> defined in the report's <ReportParameters> — including case.
  • For the no-GUI path, parameters are passed as a Dictionary<string, string> to RunGetData(parameters), not set before Parse().
  • For viewers, the Parameters string must start with &: rdlView.Parameters += "&StartDate=2024-01-01".

Sub-report not found

The engine resolves sub-report .rdl paths relative to RDLParser.Folder. If Folder is not set, the engine looks in the current working directory.

var rdlp = new RDLParser(rdlSource)
{
    Folder = Path.GetDirectoryName(rdlFilePath) // must be set
};

See Sub-reports.

Expression errors / #Error in cells

An expression error renders as #Error in the affected cell and adds a message to ErrorItems with severity 1–4 (the report still runs).

Common causes:

  • Division by zero: =Fields!Total.Value / Fields!Count.Value when Count is 0. Fix: =IIf({Count} = 0, 0, {Total} / {Count}).
  • Null reference: accessing a field that is NULL in the database. Fix: =IIf(IsNothing({Notes}), "", {Notes}).
  • Type mismatch: passing a string field to a numeric function. Fix: =CDbl({StringAmount}).

Report items extend beyond the page width

Items that exceed PageWidth − LeftMargin − RightMargin are clipped in PDF output and cause an extra blank page in some renderers.

Fix: in Report Properties, confirm the page size and margins, then check that no item's Left + Width exceeds the printable width. See Page Layout.

Extra blank page at the end of PDF

The most common cause is that the report body width slightly exceeds the printable width, forcing a second horizontal page. Check:

  1. Report Properties → Page — confirm margins.
  2. Select the body section and check its Width property — it must be ≤ PageWidth − LeftMargin − RightMargin.
  3. Check that no individual item has a right edge beyond that boundary.

Connection failure / cannot connect to database

  • Verify the connection string in the report's dataset properties.
  • For runtime override, use RDLParser.OverwriteConnectionString. See Set Connection String — Runtime.
  • For SQL Server on Linux, use the Microsoft.Data.SqlClient provider (not the legacy SQL provider name). See SQL Server Connection.
  • The error message will appear in report.ErrorItems after RunGetData.

Data provider assembly not found

RdlEngineConfig.xml references the DLL for each data provider. If the assembly is not in the expected location the engine logs an error and the dataset returns no data.

Fix: call RdlEngineConfigInit with the directory containing the provider DLL:

RdlEngineConfig.RdlEngineConfigInit(@"/custom/path/to/providers");

See Database Providers.

Performance — report is slow with large datasets

  • Add WHERE clause filters using Report Parameters rather than loading all rows and filtering in the report.
  • Use TOP / LIMIT in the SQL for preview runs while developing.
  • Avoid computed columns in the SQL that could be indexed instead.
  • For PDF/TIFF output with many pages, MemoryStreamGen holds the entire output in memory — for very large reports write to disk with OneFileStreamGen instead.
  • Complex sub-reports run one query per parent row. Cache the sub-report data in a DataTable and supply it via SubreportDataRetrieval instead of letting the engine re-query. See Sub-reports.

Clone this wiki locally