Overview
This document describes the registration issues that may occur with different registration methods and provides corresponding solutions.
License Upload Stuck
Problem:
The page is stuck during the upload of the license file.
Troubleshooting:
Go to FineReport installation directory/WEB-INF/resources, check the modification time of FanRuan.lic to determine if the upload was successful.
1. The license file failed to be uploaded.
Possible cause: The system has blocked the PUT request, causing the upload to fail.
Solution: You can install a plugin to convert PUT and DELETE requests to POST requests.
2. The license file was uploaded successfully.
Possible cause: The frontend did not refresh in time.
Solution: You can manually refresh the page and see if the registration is successful. If the registration still fails, refer to the following sections for solutions based on the error information.
License Upload Failure
Problem:
When you upload the license file, an error message pops up, saying "File FanRuan.lic can't pass validation. Please check it."
Solution:
Log in to the decision-making platform as the admin, choose System Management > Security Management> Security, disable File Upload Verification, and re-enable it after successful registration.
Expired License
Problem:
The prompt "Registration failed. Register again" is displayed during registration. Click Details, and the information is displayed:
License Expired on xxxx-xx-xx
Cause:
The registration license file used in the current project has reached the expiration date agreed upon in the contract.
Solution:
1. If the expiration date has passed, contact the sales team to renew the license.
2. If the expiration date agreed in the contract has not yet arrived, but the license has already expired, contact the sales team to obtain the correct registration license.
Version Mismatch
Problem:
The prompt "Registration failed. Register again" is displayed during registration. Click Details, and the information is displayed:
Certified App Version: Version number
Local App Version: Version number
Cause:
FanRuan products offer two types of version upgrades: major version upgrades (such as from 9.0 to 10.0 or from 10.0 to 11.0), and minor version updates (such as from 10.0.1 to 10.0.2).
1. Major version upgrades affect the license.
Major version upgrades, such as upgrading from 9.0 to 10.0, affect the license file. Re-registration or license migration is required.
2. Minor version updates do not affect the license.
Minor version updates, such as updating from 10.0.9 to 10.0.10, do not affect the license file.
Solution:
1. If you are registering a new project and the project version agreed in the contract is consistent with the product version, contact the sales team to request the correct registration license.
2. If you are registering an upgraded project, the previous registration license cannot be used. Contact the sales team for post-upgrade license migration procedures.
MAC Address Mismatch
Problem:
The prompt "Registration failed. Register again" is displayed during registration. Click Details, and the information is displayed:
Authentication MAC Address: xxx
Local MAC Address: xxx
Troubleshooting:
A media access control address (MAC address) is a unique identifier assigned to a network interface controller (NIC) for communication on a network. A device can have multiple NICs, each assigned a unique MAC address.
The MAC address in the registration license must match one of the MAC addresses of the server.
On Linux or Unix systems, the MAC address may be displayed in a different format (for example, 0x001F296EFD64) instead of the standard colon-separated format commonly seen on Windows.
| Server OS | Deployment Method | Cause & Solution |
|---|---|---|
Windows | / | Cause: The NIC has been replaced, causing the MAC address to change. Solution: Contact the business team to reauthorize the license. |
Cause: The MAC address of the server hosting the project has been changed. Solution: Solution one: Restore the MAC address to its original value. Solution two: Contact the business team to reauthorize the license. | ||
Linux | Docker | Cause: If the MAC address and the universally unique identifier (UUID) of a Docker container are not fixed, the MAC address changes randomly upon reboot. Solution: 1. You are advised to use a fixed MAC address when deploying the project in a Docker container. 2. If you prefer not to bind the MAC address, you are advised to use the private cloud/public cloud for authentication. |
Virtual machine (VM) | Cause: The MAC address of a virtual machine can be categorized into three types: 1. Fixed MAC address: The MAC address is manually configured and does not change upon reboot. 2. Same MAC address with the host: The MAC address is the same as that of the host machine and remains unchanged upon reboot. 3. Dynamic MAC address: The prefix stays the same, but the last four characters change randomly upon reboot. Solution: 1. Check if the hardware has been replaced or the system has been reinstalled on the host machine. If so, the MAC address of the VM may have changed accordingly. Contact the business team to reauthorize the license. 2. If the VM uses a dynamic MAC address, you are advised to use the private cloud/public cloud for authentication. | |
Physical machine |
Cause: You run a script as a non-root user to restart the physical machine, or you are granted the permission to run the required commands. Solution: Start the physical machine as the root user, or ensure the non-user is granted the permission to run the required demands. | |
Cause: In Linux systems, middleware (such as Tomcat) may use different MAC addresses depending on whether it is started by the root user or a non-root user. Solution: Start the physical machine as the root user to keep the MAC address consistent. |
Machine Code Mismatch
Problem:
The prompt "Registration failed. Register again" is displayed during registration. Click Details, and the information is displayed:
Authentication Machine Code: xxx
Local Machine Code: xxx
Troubleshooting:
| Factor | Cause & Solution |
|---|---|
System hardware | Cause: Replacing hardware components (such as CPU, hard drive, and motherboard) causes the machine code to change. Solution: Contact the business team to reauthorize the license. |
JDK | Cause: As the generation of the machine code depends on the JDK, changing the JDK may cause the machine code to change. Solution: Revert to the original JDK and restore the original environment variables. |
Virtual machine | Cause: Restarting the virtual machine causes the machine code to change. Solution: Contact the business team to reauthorize the license. You are advised to use the private cloud/public cloud, rather than the local machine information, for VM authentication. |
Permission | Cause: In Linux systems, middleware (such as Tomcat) may obtain different machine codes, or even fail to obtain them, depending on whether it is started by the root user or a non-root user. Start the VM as the root user to keep the machine code consistent. |
Cloud system | Cause: Configuration modification causes the machine code to change. Solution: Contact the business team to reauthorize the license. You are advised to use the private cloud/public cloud, rather than the local machine information, for VM authentication. |
Application Name Mismatch
Problem:
The prompt "Registration failed. Register again" is displayed during registration. Click Details, and the information is displayed:
Certified App Project Name: xxx
Local App Project Name: xxx
Cause:
The project URL is formatted as http://IP address:port number/project name/decision, in which port number is webroot by default.
This error usually results from a change in the project name.
Solution:
When sending an email requesting the license file to the business team:
If you have specified the project name in the email, the specified name is used in the returned license file.
If you have not specified the project name, the project name webroot is used in the returned license file.
To resolve the problem, you need to modify the project name to match the one in the license file.
License Exhausted
Problem:
The prompt "Registration failed. Register again" is displayed during registration. Click Details, and the information is displayed:
The maximum number of nodes for which licenses can be assigned has been reached.
Troubleshooting:
| Registration Method | Factor | Cause & Solution |
|---|---|---|
Local Machine Info | Multiple projects on the server | Cause: Another project running on the server is using the license. Solution: Check the modification time of the FanRuan.lic file in the path FineReport installation directory/webroot/WEB-INF/resources of other projects on the same server. If the license file is newly added, delete it and re-register the correct project. |
Repeated loading of the project | Cause: The Tomcat domain is incorrectly configured. In the server.xml file of Tomcat, two <host> entries are added, with one for the domain name and another for the IP address, causing repeated loading of the project, which further leads to the error indicating that the license is already in use. Solution: Delete the <host> entry for the IP address in server.xml and keep only the one for the domain name. The IP address can still be accessed without additional configuration. | |
Incorrect startup path | Cause: A virtual path is configured in server.xml, causing the project to start twice. Solution: Solution one: Comment out the docBase configuration in server.xml and restart Tomcat. In this way, the project can be registered normally. Solution two: Move the webroot project out of the webapps folder, specify the report project path in server.xml, and restart Tomcat. In this way, the project can be registered normally. | |
Designer registered on the server |
| |
Public cloud | License used by other projects | Cause: When requesting a public cloud license, you need to specify a maximum registration limit. If the registration limit is exceeded, the error will occur. Solution: Unbind the license from the old project and then bind it to the new project. |
Changed machine information | Cause: The machine information of the VMs changes after a restart, which may cause the registration to exceed its licensed limit. Contact technical support to check whether the public cloud license is being used by another project. Solution: Contact technical support to unbind the license and rebind it to the new project. |
Incorrect Certificate Content
Problem:
The prompt "Registration failed. Register again" is displayed during registration. Click Details. The message indicating incorrect license content is displayed.
Troubleshooting:
| Factor | Cause & Solution |
|---|---|
User permission | Cause: The user starting the project does not have the write permission on the project files. Even if 777 permissions are granted to the user, the error is still logged: "[Resource] Write failed!" Solution: Reassign the write permission on the project files to the user, or start the project as the root user. |
Repeated running of the migration program | Cause: During license migration, a new license will be generated if the migration program runs successfully for the first time. But if you run the migration program again after registering the project with the new license, the current new license will be invalidated. Solution: Contact the business team to reauthorize the license. |
Others | For more errors of this type, you need to troubleshoot them step by step based on the actual project conditions. You are advised to contact technical support if such errors occur. For details about how to contact technical support, see Technical Support Channel Introduction. Online support: You can send an email to support@fanruan.com. Phone number: 400-811-8890 |
Local Container Authentication
"All Nodes are Restarted" Error
Problem:
You have set Authentication Method to Local Container and successfully registered the project. However, after a server restart, an error is reported on the registration page with the message: "All nodes are restarted."
Cause:
If you use local container authentication, re-registration is required after a server restart by design.
Solution:
Scan the code with the mobile phone to re-register the project.
Error Code 40002
Problem:
When you scan the code with your phone to re-register a project after modifying the server configuration library and restarting the server, the error code 40002 is displayed, indicating that the license file has been used to register projects on other machines.
Cause:
If you use local container authentication, re-registration is required after the server configuration library is modified.
Solution:
Contact the business team to cancel the license of the original server and re-register using the Container.lic file sent by the business team.
Startup Exception of the Private Cloud Authentication Program
The following errors may occur if the authentication program starts abnormally. You can troubleshoot based on the error information.
| Error | |
|---|---|
Uninstalled | The license server was uninstalled previously. To use the same license server for authentication again, you need to obtain the new machine information and re-register. |
Expired | The error is related to the system time. For example, if the system time at registration is 16:18:55, 21st Dec, the private cloud takes effect at 16:40:29, 21st Dec, which may cause an expiration error. |
Error code 30002 Abnormal Account Status | 1. A possible cause is that new machine information was not generated after the original license server was removed. Instead, the original machine information was used directly, resulting in duplicate session IDs in the RIF machine information file. 2. The error may be caused by insufficient permissions of the user executing the startup command. You are advised to run the command as the root user. |
Address already in use | The port is already in use. You can start the authentication program on a different port by adding the -port option to specify a new port number in the startup command. Example: Linux/Mac: ./server -port 8090 |
Public Cloud Authentication
Network Issues
1. The report server must be connected to the license server over the public network; otherwise, projects cannot be registered through public cloud authentication.
The following external network addresses need to be accessible.
| Domain | Port |
|---|---|
cloud.fanruan.com | 443 |
shopps.finereport.com | 443 |
fine-intelli.oss-cn-shanghai.aliyuncs.com | 443 |
fine-build.oss-cn-shanghai.aliyuncs.com | 443 |
2. URL Management Center is not enabled, which prevents the project from connecting to the Internet.
Log in to the decision-making platform as the admin, choose System Management > System Setting > General, and enable URL Management Center, as shown in the following figure.
System Time Issue
Cause: The system time on the project server is inconsistent with the actual current time.
Solution: Set the system time of the server to the actual current time.
Illegal Characters in the Account
Cause: The public cloud account cannot contain Chinese characters or Chinese punctuation marks.
Solution: Contact the business team to request a new public cloud account.
Limit Exceeded
During registration, limits are enforced on the registration time, the number of data connections, concurrent IP addresses, and users. If any of these limits are reached, an error or exception will occur.
If the current project is registered, you can log in to the decision-making platform as the super admin and visit http://IP address:port number/webroot/decision/v10/register/info/license on the same page to view the limits, as shown in the following figure.
If the number of data connections reaches the limit, new data connections cannot be added or displayed.
If the number of concurrent IP addresses reaches the limit, subsequent login attempts from other IP addresses are denied.
For permanent registration, the license is valid for 100 years. After the license expires, contact the FanRuan business team for free re-registration.
Replacing server hardware may cause the machine code to change, resulting in registration failure.
Changing the project name will cause a project name mismatch, resulting in registration failure.
If the number of users reaches the limit, attempts to add new users will fail, with the error message "Conflict with other administrator operations, please refresh and try again" displayed.
If the number of distributed nodes reaches the limit, new nodes cannot be added or displayed.
Missing Function Points
When you use FineReport, certain functions may be unavailable, trigger an error, or fail to open, with an error message indicating that you are using an unregistered function, as shown in the following figure.
The error occurs because certain function points were not purchased at registration. To check the registered function points, you can log in to the decision-making platform as the admin, and choose System Management > Registration Management > Function List, as shown in the following figure.
To purchase new function points, contact the FanRuan business team at business@fanruan.com.
Coexisting Registration Methods
If the server has both a license file and a dongle, the license file takes precedence during registration.
The server will read the dongle only if the license file does not exist. In other words, MAC address–based authentication takes precedence over the dongle.
Blank Chart Caused by Unapplied License
After you register the project with a new license, charts are blank when previewed in the designer.
The issue occurs because you did not restart the web server after placing the FanRuan.lic file in FineReport installation directory/WEB-INF/resources of the project directory.
The web server must be restarted for the license to take effect.
NullPointerException (NPE)
When you preview some templates, a java.lang.NullPointerException (NullPointerException) is reported.
It occurs because the template uses some functions that are not included in your license.
