Table of Contents

Troubleshooting

Note

For more useful information about the reporting service, please visit the Neos forum "Tips and Tricks" section filtered using the stimulsoft-reports tag: https://community.neos.groupeisagri.com/tags/c/tips-and-tricks/11/stimulsoft-reports

Configuration

Do not use appsettings*.json.

Configuration values that must be shared by multiple Neos services (business cluster, proxy or gateway, and reporting server) should not be defined only in appsettings.json / appsettings.Development.json files.

When configuration is placed in the appsettings*.json file of the business cluster, only the business cluster will read these values, while the proxy/gateway and the reporting server will not have access to them. This can cause inconsistent behavior, particularly with PDF generation and storage configurations.

Solution: Place shared environment variables in one of these locations instead:

  • PowerShell profile file (defined by $PROFILE variable)
    • Example: $env:UserProfile\OneDrive - GROUPE ISAGRI SERVICES\Documents\PowerShell\Microsoft.PowerShell_profile.ps1
  • System or user environment variables via SystemPropertiesAdvanced.exe

This ensures all three services (business, proxy/gateway, and reporting) use the same configuration values.

Run neos run with a specific report persistence mode in development

By default in local development, report persistence should remain in filesystem mode.

Use one of the following PowerShell snippets before running neos run:

  • Legacy mode (database payload/Base64 flow)
$env:NeosReportLegacyMode = "true"

# Prevent accidental S3 activation from previous shell values.
Remove-Item Env:AWS__ServiceURL -ErrorAction SilentlyContinue
Remove-Item Env:AWS__BucketName -ErrorAction SilentlyContinue
Remove-Item Env:AWS__AccessKey -ErrorAction SilentlyContinue
Remove-Item Env:AWS__SecretKey -ErrorAction SilentlyContinue
Remove-Item Env:AWS__Region -ErrorAction SilentlyContinue

neos run -r
  • Filesystem mode (recommended default in development)
$env:NeosReportLegacyMode = "false"

# S3 mode is enabled when AWS__BucketName is set. Ensure it is not present.
Remove-Item Env:AWS__BucketName -ErrorAction SilentlyContinue
Remove-Item Env:AWS__ServiceURL -ErrorAction SilentlyContinue
Remove-Item Env:AWS__AccessKey -ErrorAction SilentlyContinue
Remove-Item Env:AWS__SecretKey -ErrorAction SilentlyContinue
Remove-Item Env:AWS__Region -ErrorAction SilentlyContinue

neos run -r
  • S3 mode (for local validation of S3 persistence)
$env:NeosReportLegacyMode = "false"
$env:AWS__BucketName = "neos-reports"
$env:AWS__ServiceURL = "http://127.0.0.1:9000"
$env:AWS__AccessKey = "<access-key>"
$env:AWS__SecretKey = "<secret-key>"
$env:AWS__Region = "us-east-1"

neos run -r

The S3 mode requires at least the AWS__BucketName to be set. Depending on your S3-compatible service, you may also need to set AWS__ServiceURL, AWS__AccessKey, AWS__SecretKey, and AWS__Region.

S3 persistence is only supported for business cluster versions 3.2 and later. If you deploy an older business cluster into an environment where report S3 is configured globally, set clusters[].reportLegacyMode: true (mono-tenant) or clusters[].versions[].reportLegacyMode: true (multi-tenant) so it continues to use the legacy Pub/Sub payload flow.

In deployed Helm environments, both filesystem mode and S3 mode serve download and print requests from the reporting server. If users can generate reports but fail to download them, inspect the report server configuration and gateway reporting routes first. Legacy mode is the only mode where the cluster backend serves the download.

Designer

I added a second datasource but it's not working.

In Neos, we can only manage one DataSource of type entity view.

I don't see my DataSource in the list of Connections.

If you just added an entity view, there is a cache, and you need to restart the neos command.

Otherwise, does your entity view end with the View suffix?

The report designer Preview tab fails to load.

To generate a report containing actual data, the Preview feature needs to retrieve data from the application. To do so, it requires:

  • Authentication with the localhost application domain (*).
  • A valid payload for the application endpoint.

As a result, we recommend that you:

  • Connect to the application at least once before using the Preview feature.
  • Use a ReportGenerationConfig sheet if your endpoint requires parameters.

(*) Starting from 3.2.0, you should get an explicit error message when this occurs "Access denied (401 Unauthorized): you do not have permission to preview this report. Ensure your local development application is running and authenticated before using preview features."

Online Viewer (iFrame)

I use my report in several places with different filters but it opens in the same tab and the viewer does not refresh.

When opening a report viewer by code, you need to use the Title option. Set a different title for each use case.

Culture

Strings handled by Stimulsoft are not formatted in my culture.

If you are working with one single culture, please make sure that you have set a reference culture in the template.

If you are working with an alternative culture, please provide content translation in the template and use the Culture option.

Performance

The report times out or takes a long time to show in the Viewer.

One needs to be careful with the DataSource and especially with DateTime properties.

  1. If the property is nullable, you should edit the type of the property and use the type "DateTime (Nullable)".

  2. You should review the content of the MRT file and search for unwanted TextFormat attributes. For instance, one should never attempt to format a standard text as DateTime: this would cause silent internal errors and seriously degrade generation performance.

Backend generations

The reporting server doesn't start automatically when I generate reports from business assemblies.

The reporting server auto-start feature only applies to requests initiated from the client browser (ExecuteReportAsync or ShowReportAsync).

For generation requests initiated by business assemblies (IReportGenerator), you need to manually start the reporting server using the --reporting (-r) option with neos run.

Alternatively, if you already started neos run without the --reporting (-r) option, you can still start the reporting service manually via the manager (https://localhost/neos/<ClusterName>/manage/).

Backend report generation fails when using neos run -dp:false.

Prior to v3.0, when running the development server without Dapr the --dapr false (-dp:false) option, backend report generation through IReportGenerator will not work properly. This configuration disables the development proxy which is required for proper communication between the backend services and the reporting server (in particular the transmission of the serialized callback expression).

Solution: Remove the -dp:false option when you need to generate reports from business assemblies. The development proxy is essential for coordinating the reporting service with your backend code.

This incompatibility was tracked as issue #30622 and is now closed.

Deployment

I have compatibility issues when mixing Business 2.3 (or older) with Reporting 2.4 (or later).

If you're running Business assemblies based on Neos 2.3.12 (or older) with a Reporting server version 2.4 (or later), you may encounter compatibility issues when generating reports from backend code (IReportGenerator).

This scenario requires the 2.3.13 forward compatibility patch to ensure proper communication between the different versions.

Solution: Update your Business assemblies to Neos version 2.3.13 or later, which includes the forward compatibility patch for the Neos Reporting service 2.4+.

PDF

The generated report doesn't include my font in a deployed environment.

Please see this article for more detail on how to configure fonts for production.