Fix XRay Configuration Error: Empty PrivateKey in 3x-UI Reality

The XRay configuration error in your 3x-ui panel is caused by an empty privateKey field in the REALITY config. To fix this, you need to generate a valid X25519 private key using either the 3x-UI API, OpenSSL, or the XRay CLI tool, then add it to your config.json file.

Contents

• Understanding the XRay REALITY Configuration Error
• How to Fix the Empty PrivateKey Error in 3x-UI
• Method 1: Using the 3x-UI Panel API
• Method 2: Manual Key Generation with OpenSSL
• Method 3: Using XRay CLI for Key Generation
• Verifying and Testing Your Configuration

Understanding the XRay REALITY Configuration Error

The error you’re experiencing is specifically related to the REALITY configuration in your XRay setup. When the XRay service tries to start, it checks the configuration file (bin/config.json) and encounters an empty privateKey field in your REALITY inbound configuration. This is a common issue that can occur when:

1. The REALITY configuration was manually edited and the private key was accidentally removed
2. The configuration file was corrupted or improperly updated
3. The initial setup didn’t properly generate a private key
4. There was a version update that changed configuration requirements

The error message specifically points to this issue:

2026/02/16 14:11:30 ERROR - XRAY: Failed to start: main: failed to load config files: [bin/config.json] > infra/conf: failed to build inbound config with tag inbound-443 > infra/conf: Failed to build REALITY config. > infra/conf: empty "privateKey"

This tells us that the REALITY config is missing the required private key, which is essential for the X25519 key exchange protocol used by REALITY. Without this key, XRay cannot properly encrypt and decrypt traffic.

REALITY is a modern protocol designed to provide strong encryption while appearing as regular HTTPS traffic. It requires both a private and public key pair for the server to function correctly.

How to Fix the Empty PrivateKey Error in 3x-UI

Resolving this issue requires generating a valid X25519 private key and adding it to your configuration. There are three primary methods to accomplish this:

1. Using the 3x-UI Panel API - This is the recommended method as it integrates directly with your panel
2. Manual Key Generation with OpenSSL - For users comfortable with command line tools
3. Using XRay CLI for Key Generation - If you have XRay CLI installed

Each method will generate a proper private key that you can then add to your bin/config.json file. After adding the key, you’ll need to restart the XRay service for the changes to take effect.

The key point to understand is that the REALITY protocol requires a valid X25519 private key to establish secure connections. This key is used in the encryption process and is unique to your server configuration.

Method 1: Using the 3x-UI Panel API

This is the most straightforward method if your 3x-UI panel is accessible via its web interface. The panel includes an API endpoint specifically for generating new X25519 certificates.

Step-by-step process:

1. Log in to your 3x-UI panel through the web interface
2. Navigate to the Server API section (usually found in settings or advanced options)
3. Locate the Get new X25519 certificate endpoint. This is typically available at:

GET /panel/api/server/getNewX25519Cert

4. Call this endpoint to generate a new private key. You may need to use your browser’s developer tools or a tool like curl to make this API call.
5. The API will return a JSON response containing the new privateKey value
6. Copy the privateKey value from the response

Now, you need to add this key to your configuration:

1. Open the bin/config.json file on your server using a text editor
2. Navigate to the REALITY inbound configuration section
3. Find the privateKey field and replace its empty value with the key you copied
4. Save the file

Finally, restart the XRay service:

1. Go back to the 3x-UI panel
2. Find the Restart Xray Service button or API endpoint:

POST /panel/api/server/restartXrayService

3. Click the button or call the endpoint to restart the service

After the restart, your XRay service should be working with the new private key. According to the 3x-UI documentation, this method is officially supported and should resolve the empty privateKey error.

Method 2: Manual Key Generation with OpenSSL

If you prefer to generate the key manually or don’t have access to the 3x-UI API, you can use OpenSSL to generate the required X25519 private key.

Step-by-step process:

1. Connect to your server via SSH
2. Run the following command to generate a new X25519 private key:

openssl genpkey -algorithm X25519 -out private.key

3. This will create a file named private.key containing the private key
4. View the contents of the file with:

cat private.key

5. Copy the private key value (it starts with -----BEGIN PRIVATE KEY----- and ends with -----END PRIVATE KEY-----)

Now, add this key to your configuration:

1. Open the bin/config.json file using a text editor like nano or vim:

nano bin/config.json

2. Navigate to the REALITY inbound configuration section
3. Find the privateKey field and replace its empty value with the key you copied
4. Save the file and exit the editor

Restart the XRay service through the 3x-UI panel or using the command line:

systemctl restart x-ui

This method gives you full control over the key generation process and is particularly useful if you need to generate multiple keys or want to verify the key generation process yourself.

Method 3: Using XRay CLI for Key Generation

If you have the XRay CLI installed on your server, you can use it to generate the required X25519 private key. This is particularly useful if you already have XRay CLI set up for other operations.

Step-by-step process:

1. First, check if you have the XRay CLI installed by running:

xray --version

2. If installed, use the x25519 command to generate a new key pair:

xray x25519

3. This command will output both the private key and public key
4. Copy the private key value (it will be clearly marked as “Private key”)

Add this key to your configuration:

1. Open the bin/config.json file using your preferred text editor
2. Navigate to the REALITY inbound configuration section
3. Find the privateKey field and replace its empty value with the key you copied
4. Save the file

Restart the XRay service:

systemctl restart x-ui

The XRay CLI method is convenient if you’re already working with XRay tools and prefer to keep all operations within the XRay ecosystem. According to the XRay documentation, the x25519 command specifically generates key pairs for X25519 key exchange used in REALITY and VLESS Encryption protocols.

Verifying and Testing Your Configuration

After adding the private key to your configuration and restarting the XRay service, it’s important to verify that everything is working correctly.

Verification steps:

1. Check the XRay service status:

systemctl status x-ui

The service should show as “active (running)”

2. Check the XRay logs for any remaining errors:

journalctl -u x-ui -f

Look for any error messages related to the REALITY configuration

3. If the service is running without errors, test your VLESS connection:

• Use a VLESS client to connect to your server
• Verify that you can establish a connection
• Check if traffic is being properly routed through the tunnel

4. If you encounter issues, double-check your configuration:

• Ensure the private key was correctly copied (no extra spaces or characters)
• Verify that the REALITY configuration in bin/config.json is properly formatted
• Check that all required fields in the REALITY config are present

5. Common issues to watch for:

• Missing commas in the JSON configuration
• Incorrect indentation
• Extra spaces in the private key value
• Mismatched server names in the REALITY config

If the service still doesn’t start, you may need to:

• Generate a new private key using one of the methods described
• Check if there are any issues with your server’s OpenSSL installation
• Verify that your server meets the requirements for the XRay version you’re using

Remember that the REALITY protocol is designed to be stealthy and appear as regular HTTPS traffic, so your server should respond normaly to HTTPS requests while also accepting VLESS connections through the same port.

Sources

1. 3x-UI Configuration Wiki — Official documentation for resolving empty privateKey errors in REALITY config: https://github.com/MHSanaei/3x-ui/wiki/Configuration
2. XRay CLI Documentation — Official XRay command line interface documentation including x25519 key generation: https://xtls.github.io/en/document/command.html
3. XRay REALITY Configuration Example — Example REALITY config showing proper privateKey placement: https://github.com/XTLS/Xray-examples/blob/main/VLESS-TCP-XTLS-Vision-REALITY/config_server.jsonc
4. 3x-UI GitHub Issues — Real user experiences with XRay configuration errors: https://github.com/MHSanaei/3x-ui/issues/2830
5. 3x-UI GitHub Issues — Additional troubleshooting information for XRay service failures: https://github.com/MHSanaei/3x-ui/issues/3178

Conclusion

The empty privateKey error in your XRay REALITY configuration is a common issue that can be resolved by generating a valid X25519 private key and adding it to your bin/config.json file. We’ve explored three effective methods: using the 3x-UI panel API, generating keys with OpenSSL, and using the XRay CLI tool.

Each method provides a way to generate the required private key, but the API method is recommended as it specifically designed for the 3x-UI panel and minimizes the risk of configuration errors. After adding the private key and restarting the XRay service, your VLESS connections should work properly with the enhanced security provided by the REALITY protocol.