FineOps Deployment Troubleshooting

Version Description

Application Scenario

This document introduces common issues and solutions for deploying and upgrading FineOps.

Privileges Required for Non-root Users to Run finekey

You are highly advised to use the root user to run the finekey deployment tool.

If you need to use a non-root user to run finekey, configure the user privilege by referring to User Permission Confirmation.

Reasons for Deployment Failure When the Disk Space is 100 GB

1. The directory is incorrect.

The default installation path is ~/data, which is the data folder in the home directory of the installation user, not the data folder in the root directory.

For example, if you deploy FineOps using the root user, ~/data represents /root/data. Ensure that the path in the YAML file is configured correctly.

2. The available disk space is insufficient.

The mounting directory must have at least 100 GB of available disk space.

The operating system occupies some space on the server. Therefore, if you allocate only 100 GB to that directory, the actual available space will be less than 100 GB, failing to meet the requirement.

finekey is already running

Error message: finekey is already running

Cause analysis: The finekey tool is already running. You need to terminate the process occupying the tool before restarting the tool.

Solution:

• If another user is running finekey, wait for completion.

• If you are sure it is safe to interrupt the execution, run ps -ef | grep finekey to find the process ID (PID), and then run kill -9 PID to terminate it.

The current path capacity check failed

Error message:

The current path capacity check failed, please re-enter the path

Enter the folder path and press ENTER to confirm, or enter g then ENTER to exit:

Cause analysis:

FineOps requires sufficient server disk space for deployment.

During deployment, it automatically checks whether the partition corresponding to dataRootPath in the finekey.yaml file has enough available space.

dataRootPath defaults to ~/data. Note that this refers to the data directory in the current user's home directory, not /data. For example, if you deploy FineOps using the root user, ~/data means /root/data.

Solution:

If the path was entered incorrectly, you do not need to exit deployment. Enter a valid path in the YAML file and continue deployment.

If the directory is correct but disk space is insufficient, contact O&M personnel to expand server storage. This is a prerequisite for deploying FineOps and must be met.

disk available capacity: xxx, less than xxxG

Error message: ERROR: 2022/05/18 17:08:36 node 192.168.1.24 disk available capacity: 3789952, less than 100G

Cause analysis:

FineOps requires sufficient server disk space for deployment.

During deployment, it automatically checks whether the partition corresponding to dataRootPath in the finekey.yaml file has enough available space.

Solution:

1. Open the configuration file finekey.yaml in finekey installation directory/conf, and check the server directory corresponding to dataRootPath.

The default path is ~/data, which is the data folder in the user's home directory. For example, if you deploy FineOps using the root user, ~/data means /root/data.

2. Run df -h to check the available disk space on the server.

3. Ensure that the available space on the disk partition corresponding to dataRootPath exceeds the indicated value. This is a prerequisite for deploying FineOps and must be met.

If disk space is insufficient, contact O&M personnel to expand server storage or use a directory with sufficient space as dataRootPath.

Do not use system directories as dataroot

Error message: Do not use system directories as dataroot!

Cause analysis: /, /usr, /root, and /usr/local are system paths and cannot be used as dataRootPath in the finekey.yaml file.

Solution:

Open the configuration file finekey.yaml in finekey installation directory/conf, and modify the dataRootPath setting.

Do not use /, /usr, /root, or /usr/local. Use other paths or create new folders within these paths.

memory available capacity: xxx, less than xxG

Error message: ERROR: 2022/04/20 14:12:55 node 192.168.101.144 memory available capacity: 7302952, less than 12G

Cause analysis: FineOps requires sufficient server memory to run. During deployment, FineOps automatically checks whether the server has enough available physical memory.

Solution: This is a prerequisite for deploying the operations platform and must be met. Contact the relevant O&M personnel to increase the server configuration.

connection refused

Error message: ERROR: 2022/05/18 17:33:07 finedb connect error:dial tcp 192.168.1.24:3306: connect: connection refused

Cause analysis: The relevant ports configured in the finekey.yaml file are not open, resulting in connection failure.

Solution: Check whether the ports mentioned in the error message are allowed in the firewall, security group, and other settings. For details, see Port Occupancy Inspection and Firewall Configuration.

try bind ports xx error

Error message:

ERROR: 2025/10/15 21:41:49 183.6.186.178 :try bind ports 80 error

ERROR: 2025/10/11 15:26:19 10.38.6.26 :try bind ports 9200,9071,12800,11800,80 error

Cause analysis:

FineOps consists of multiple containers, and some of them require port mapping to the host machine, occupying server ports for operation.

During deployment, if the container-required ports are found to be occupied, this error occurs.

Solution:

Check whether the ports mentioned in the error message are occupied. For details, see Port Occupancy Inspection and Firewall Configuration.

• If the ports are indeed occupied, open the configuration file finekey.yaml in finekey installation directory/conf, locate the corresponding component, modify the mapped ports in portMapping, save the change, exit editing, and then perform redeployment.

• If the ports are not occupied, open finekey.yaml and check for formatting errors such as missing spaces or using Chinese symbols.

mapping values are not allowed in this context

Error message: ERROR: 2022/04/20 13:56:28 parse config file /Users/carly/finekey/conf/finekey.yaml error: yaml: line 14: mapping values are not allowed in this context

Cause analysis: YAML files have strict formatting requirements. This error is most likely caused by formatting issues in the content.

Solution: Open the configuration file finekey.yaml in finekey installation directory/conf and correct the formatting according to the line number indicated in the error message.

add user to docker group error

Error message: add user to docker group error: sudo: 1 incorrect password attempt

Solution:

1. Open the configuration file finekey.yaml in finekey installation directory/conf and verify that the username and password in the node configuration are correct.

2. Ensure that the server where the finekey tool is located can access the server where FineOps is to be deployed via an SSH connection.

3. If the issue is related to the remote connection tool, close and restart the tool, and try again.

ssh connect error

Error message: ERROR: 2022/04/20 13:58:14 node:192.168.101.144 ssh connect error:ssh: handshake failed: ssh: unable to authenticate, attempted methods

Cause analysis: The SSH connection failed. The string unable to authenticate in the error details indicates an incorrect password, and Connection refused indicates a network issue.

Solution:

1. Open the configuration file finekey.yaml in finekey installation directory/confand verify that the username and password in the node configuration are correct.

2. Ensure that the server where the finekey tool is located can access the server where FineOps is to be deployed via an SSH connection.

3. If the issue is related to the remote connection tool, close and restart the tool, and try again.

did not find expected key

Error message:

ERROR: 2022/04/20 13:58:14 parse config file /home/finekey/conf/finekey.yaml error: yaml: line 26: did not find expected key

Possible reasons and troubleshooting:
1. YAML format error

YAML files have strict formatting requirements. This error is most likely caused by formatting issues in the content.

Open the configuration file finekey.yaml in finekey installation directory/conf and correct the formatting according to the line number indicated in the error message.

2. Unremoved comments

This error often occurs when comments for component ports are not fully removed.

Open the configuration file finekey.yaml in finekey installation directory/conf and ensure that the #Comment part has been deleted from lines where components, component names, or component port configuration are located.

Take changing the Nginx port from 80 to 8088 as an example.

#Component port configuration
#components:
#  nginx:
#    portMapping: {80: 8080}
#
#  ops_agent:
#    portMapping: {9071: 9070}

#Component port configuration
components:
  nginx:
    portMapping: {8088: 8080}
#
#  ops_agent:
#    portMapping: {9071: 9070}

node xxx get runc command location not /usr/bin/runc but /usr/local/bin/runc

Error message: get runc command location not /usr/bin/runc but /usr/local/bin/runc

Cause analysis:

Docker and its components installed by finekey must be those provided by FanRuan to pass the deployment checks, ensuring compatibility.

If other software on the server has installed runc of an outdated version, runc may conflict with Docker installed by FanRuan, leading to deployment failure.

Solution:

1. Run which runc to check whether runc is the FanRuan-provided one located at /usr/bin/runc.

2. Run rpm -qa | grep podman to check whether podman is installed. Podman typically includes runc of an outdated version.

3. If podman is not needed, run yum remove podman -y to uninstall it.

docker bin path check not pass

Error message:

docker bin path check not pass, using commands like [rpm -qa | grep podman] to find out other OCI management tools like [podman], using [yum remove podman] to remove them and retry

Cause analysis:

Docker and its components installed by finekey must be those provided by FanRuan to pass the deployment checks, ensuring compatibility.

If other software on the server has installed runc of an outdated version, runc may conflict with Docker installed by FanRuan, leading to deployment failure.

Solution:

1. Run which runc to check whether runc is the FanRuan-provided one located at /usr/bin/runc.

2. Run rpm -qa | grep podman to check whether podman is installed. Podman typically includes runc of an outdated version.

3. If podman is not needed, run yum remove podman -y to uninstall it.

node selinux status check got [enforcing] status

Error message:

node selinux status check got [enforcing] status, please using [setenforce 0 && sed -i s/^SELINUX=enforcing/SELINUX=permissive/ /etc/selinux/config] to disable selinux

Cause analysis:

Security-Enhanced Linux (SELinux) is a security module integrated into the Linux kernel, which strictly restricts access to system resources by programs and users via mandatory access control mechanisms. The enabled SELinux may interfere with starting Docker as a service using the systemctl command.

To ensure successful deployment using finekey, disable SELinux or switch it to the permissive mode before deployment. This prevents operations that violate SELinux policies from being blocked.

Solution:

1. Disabling SELinux is preferred. For details, see Ensuring SELinux is Disabled.

2. Alternatively, use the following commands to switch SELinux to the permissive mode, as indicated in the error message:

setenforce 0 && sed -i s/^SELINUX=enforcing/SELINUX=permissive/ /etc/selinux/config

• setenforce 0: It switches SELinux from the enforcing mode to permissive temporarily.

• sed -i s/^SELINUX=enforcing/SELINUX=permissive/ /etc/selinux/config: It modifies the SELinux configuration file by changing the default mode from enforcing to permissive.

The network segment xxx is already in use by other machine

Error message: The network segment *.*.*.*/16 is already in use by other machine. Please choose another network segment.

Cause analysis:

BIP (Bridge IP) is the IP address of Docker's default network bridge, docker0. All containers without a specified network are attached to this bridge and obtain a subnet IP address from it.

Under normal circumstances, you do not need to specify a BIP. However, if this error occurs, you must assign an unused private network segment to BIP.

Solution:

1. Open the configuration file finekey.yaml in finekey installation directory/conf.

2. Uncomment the line containing bip.

3. Modify the bip value to an unused private network segment.

IP address xxx is already in use within the network segment xxx

Error message: Conflict detected: IP address 172.18.8.175 is already in use within the network segment 172.18.0.0/16.

Cause analysis:

BIP (Bridge IP) is the IP address of Docker's default network bridge, docker0. All containers without a specified network are attached to this bridge and obtain a subnet IP address from it.

Under normal circumstances, you do not need to specify a BIP. However, if this error occurs, you must assign an unused private network segment to BIP.

Solution:

1. Open the configuration file finekey.yaml in finekey installation directory/conf.

2. Uncomment the line containing bip.

3. Modify the bip value to an unused private network segment.

can not connect to ImageRegistry or CloudSite!

Error message: ERROR: 2025/03/18 10:30:04 172.24.27.10 :can not connect to ImageRegistry or CloudSite!

Cause analysis:

FineOps consists of multiple containers that rely on images for installation.

If you use the online version of finekey to deploy FineOps, the server must have access to the internet to pull images from FanRuan’s cloud image repository to the local repository.

This error indicates that the online version of finekey is being used, but the server cannot access the internet, making it impossible to obtain the images for deployment.

Solution:

1. If the server supports an internet whitelist:

Ensure that the server where FineOps is to be deployed (or the self-provided image repository server) has its network whitelist configured. This allows the system to automatically pull the latest component images from FanRuan’s cloud repository during deployment.

For details, see Ensuring Access to FanRuan Cloud Repository.

2. If the server does not support the internet whitelist:

Do not use the finekey installation package of the online version. Instead, use the full offline version for deployment.

registry is not ready!

Error message: registry is not ready!

Scenario one: Using a self-provided image repository

1. Verify that the image repository address, username, password, and other configuration are correct.

• Open the configuration file finekey.yaml in finekey installation directory/conf.

• Verify that the repository-related information is input correctly.

2. Ensure that the image repository is running properly.

Scenario two: Deploying a new image repository

During finekey-based FineOps deployment, the first container to be installed/connected is registry. This error may be caused by container installation issues or system network issues.

Run docker ps -a | grep registry to check whether the registry container process exists, then proceed based on the return value.

ifconfig docker0 promisc

ifconfig br-fanruan promisc

External Addresses Required for Online Upgrades

For internal network environments, if you need to upgrade FineOps online, you must configure the network whitelist accordingly.

For details, see Ensuring Access to FanRuan Cloud Repository.

docker engine Error in Upgrades

Issue description:

During a FineOps upgrade, an error related to the Docker engine occurs.

Cause analysis:

There is a dependency between the Docker engine, FineOps, and the OPS Agent component of the project.

To manually upgrade FineOps, you must ensure that both the FineOps server and the servers hosting the projects managed by FineOps support Docker engine upgrades.

If the current environment does not support Docker engine upgrades during the execution of the finekey update command, this error is triggered, and the upgrade is interrupted.

Solution:

1. Log in to the FineOps server and each server hosting the projects managed by FineOps.

2. Execute ./finekey engine --update to upgrade the Docker engine.

3. Rerun the upgrade command ./finekey update.

Note that:

During FineOps upgrades, if the Docker engine upgrade is triggered on a server, the containers on that server will be restarted.

This will affect end users using FineOps and the projects. Therefore, perform the upgrade during non-working hours to minimize business impact.