In the process of using Linux to build a remote graphical desktop environment, VNC is one of the widely used solutions. However, in actual operation and maintenance, many users will encounter problems such as "VNC connection failure", "black screen", "connection timeout", etc. There are many reasons for VNC connection failure, which may involve multiple levels such as network, firewall configuration, VNC service status, desktop environment problems, permission settings, and password errors.

Before starting to troubleshoot, first clarify what the problem is, which is the first step in positioning. VNC connection failures can be roughly classified into the following categories:

• The client prompts "Connection timed out" or "Connection refused"
• After successful connection, the screen is black and unresponsive
• The login interface is normal but disconnects after entering the password
• Multiple users cannot connect concurrently
• Connection is successful but the mouse and keyboard are unresponsive or the screen is distorted

The reasons behind each phenomenon may be different. The following troubleshooting suggestions can be handled one by one according to the problem type.

The first step of troubleshooting: Is the service running normally?

1. Check whether the VNC service is started

Use the following command to view the VNC service status of the currently logged in user:

vncserver -list

If the output is empty or there is no session such as :1, :2, etc., it means that VNC is not started correctly.

Startup command example:

vncserver :1

2. Check the log file for any abnormalities

VNC will write the startup log to the ~/.vnc/*.log file, for example:

cat ~/.vnc/your-hostname:1.log

Pay attention to the following error keywords:

"Fatal server error"
"Cannot open display"
"Authentication failure"
"Font path error"
"xstartup permission denied"

The above words basically indicate that the server startup failed and the configuration needs to be checked.

The second step is to check: Is the network connection smooth?

VNC uses TCP 5900+n ports (n is the display number), starting from 5901 by default. If the connection times out or is rejected, it may be that the network is not connected or blocked by the firewall.

1. Local test port listening

netstat -tulnp | grep 5901

Or use the ss command:

ss -tnlp | grep 5901

If there is no monitoring, it means that the server VNC is not bound to the port or failed to start.

2. The client tests whether the port is accessible

Use telnet or nc to test from the remote client:

telnet server_ip 5901

or:

nc -zv server_ip 5901

"Connection refused" indicates that the port is not listening; "Connection timeout" may be blocked by the firewall.

3. Firewall or SELinux check

CentOS/RHEL firewall:

firewall-cmd --list-ports
firewall-cmd --add-port=5901/tcp --permanent
firewall-cmd --reload

Ubuntu UFW：

sudo ufw allow 5901/tcp

SELinux status check:

sestatus

If it is Enforcing, you can temporarily turn off the test:

sudo setenforce 0

Step 3: Check if the desktop environment is loaded correctly?

Even if the VNC port monitoring is normal, if the graphical desktop is not loaded or configured incorrectly, it will cause a black screen or no response.

1. Check the xstartup configuration file

The VNC startup script ~/.vnc/xstartup needs to load the correct desktop environment command. For example:

XFCE desktop:

#!/bin/sh
xrdb $HOME/.Xresources
startxfce4 &

Gnome Desktop:

#!/bin/sh
exec gnome-session &

MATE Desktop:

#!/bin/sh
exec mate-session &

Note that the file must have executable permissions:

chmod +x ~/.vnc/xstartup

2. Is the desktop environment installed completely?

Sometimes users think the desktop environment is installed, but key components are missing. It is recommended to check whether the following packages are installed:

sudo yum group list
sudo apt list --installed | grep xfce

If there are any omissions, use the following command to complete them:

# CentOS XFCE
sudo yum groupinstall "Xfce"

# Ubuntu XFCE
sudo apt install xfce4 xfce4-goodies -y

Step 4: Check: Are the permissions and user environment configurations reasonable?

1. Does the current user have VNC usage permissions?

It is recommended to use a non-root user to run VNC by default, ensuring the following points:

• Have local directory permissions
• vncpasswd has been set
• xstartup belongs to the correct user

Repair the permissions using the following command:

chown -R youruser:youruser ~/.vnc

2. Are there conflicts among multiple users?

If multiple users try to share the same display (such as :1), the system may refuse to connect or a session conflict may occur. It is recommended that each user configure an independent display:

• user1：:1(5901)
• user2：:2(5902)

Step 5: Check: Are the client settings correct?

Sometimes it is not a server problem, but a client software connection parameter configuration error.

1. Is the address format correct?

The VNC client connection format is:

IP:DISPLAY
或
IP::PORT

For example:

192.168.1.100:1
192.168.1.100::5901

::5901 is the full TCP port format and :1 is the logical display number.

2. Are incompatible encryption options enabled?

Some VNC clients (such as TigerVNC, RealVNC) have encryption layers enabled, which may conflict with non-SSL servers.

Try using the following parameters:

• No Encryption
• Enable "Compatibility Mode"
• Start server-side testing with -SecurityTypes=None

vncserver :1 -SecurityTypes=None

VNC remote connection failure is one of the most common problems in Linux graphical remote deployment, but it can usually be quickly located and fixed by systematically checking the network, services, configuration, permissions, and client parameters. A well-structured and well-documented operation and maintenance process will greatly improve the availability and security of the VNC remote desktop system.