Table of Contents

Troubleshooting

Products: FastReport Corporate Server

If you encounter any issues during installation or startup, this section will help you resolve them.

Migrations

The corporate server is designed to automatically apply database migrations on startup. Manual migration control is generally not available to end users.
Although the server includes a built-in recovery mechanism, certain issues may arise from external factors unrelated to the server itself — for example, power outages or network interruptions.

If the connection to the database is lost during a migration process, the system will activate a lock mode and prevent the backend from starting, in order to avoid database corruption. In such cases, manual migration recovery will be required.

Important: It is strongly recommended to create a backup of the database before upgrading the corporate server version. This ensures that you can restore the database and restart the server if anything goes wrong.

If no backups are available, developer tools are available for use. Please note that using these tools may result in data loss; however, they can help recover database integrity and allow the corporate server to run again.

To access the developer tools, proceed to the corresponding section.

Developer Tools

The standard distribution of the corporate server supports deployment via docker-compose and Kubernetes. This documentation covers only these two deployment methods.
If you encounter any issues or require additional assistance, please contact our technical support team.

Docker

To use the developer tools, you must first stop the running backend instance to avoid conflicts. Follow the steps below:

  1. Check Running Containers

List all active containers:

docker-compose -f /path/to/folder/docker-compose.yml ps

Note: All commands require the docker-compose.yml file. Ensure that the current directory contains this file, or specify its location using the -f parameter.

  1. Stop the Backend Container

Stop the relevant container (e.g., fr-backend):

docker-compose -f /path/to/folder/docker-compose.yml stop fr-backend
  1. Run a New Container with Developer Tools

Create a new container and attach it to the same network used in your docker-compose.yml file.

First, check available networks:

docker network ls

Then, run the container. Replace debian-2026.2.13 with the appropriate tag from your docker-compose.yml file:

docker run -it --network corporate_fr-cs -v /path/to/folder/appsettings.Production.json:/app/appsettings.Production.json fastreport-corporate-server-backend:debian-2026.2.13 /bin/bash

Once inside the container, launch the utility:

dotnet FastReport.Cloud.Backend.dll -- --corporate-dev-tools

Follow the on-screen instructions. When done, exit the terminal:

exit
  1. Restart the Main Service

After completing the tool operations, restart the backend service:

docker-compose -f /path/to/folder/docker-compose.yml start fr-backend

Kubernetes

To use the developer tools, you need to temporarily stop the running backend instance. Follow these steps:

  1. Check Deployment Status

Retrieve a list of running deployments. Note the current number of replicas — you will need this value later:

kubectl get deployments --namespace fr-corporate

Important: Replace fr-corporate with your actual namespace if different.

  1. Stop Pods by Scaling Replicas to Zero

Scale the deployment to zero replicas to stop all associated pods:

kubectl scale --replicas=0 deployment/fr-backend --namespace fr-corporate
  1. Launch a Container with Developer Tools

Create a file named my-debug-pod.yml with the following content:

apiVersion: v1
kind: Pod
metadata:
  name: my-debug-pod
  namespace: fr-corporate
spec:
  containers:
    - name: app
      image: fastreport-corporate-server-backend:debian-2026.2.13
      command: ["/bin/bash"] 
      args: ["-c", "while true; do sleep 10; done"]
      tty: true
      volumeMounts:
        - mountPath: /app/appsettings.Production.json
          name: config-volume
          subPath: appsettings.Production.json
  volumes:
    - name: config-volume
      configMap:
        name: fast-report-config
        items:
          - key: appsettings.Production.json
            path: appsettings.Production.json
        defaultMode: 420

Apply the manifest:

kubectl apply -f my-debug-pod.yml --namespace fr-corporate
  1. Connect to the Pod

Access the container:

kubectl exec -it my-debug-pod --namespace fr-corporate -- /bin/bash

Run the developer utility:

dotnet FastReport.Cloud.Backend.dll -- --corporate-dev-tools

Follow the on-screen instructions. When finished, exit the shell:

exit
  1. Delete the Debug Pod

After completing the tasks, remove the temporary pod:

kubectl delete pod my-debug-pod --namespace fr-corporate
  1. Restore Replica Count

Return the deployment to its original replica count (e.g., 1):

kubectl scale --replicas=1 deployment/fr-backend --namespace fr-corporate