Xray Core critical error and core startup error
- Author
- Dmitry Sokolov, Lead technical writer
- Reviewed by:
- Artem Volkov
- Fact-checked:
- Published:
- Guide version:
- 1.0
In short
A critical Xray Core error in Happ means the core failed to start or crashed. Try another server, turn off the routing profile, close programs that use local ports, and update Happ.
Happ builds a configuration and passes it to the Xray-core engine, which establishes the connection. If the configuration is invalid or the core lacks a resource, it stops, and Happ shows a critical error or a core startup error. The most common culprits are an invalid JSON config, parameters the current core version does not support, missing categories in the geo files, and busy local ports. Less often, an antivirus blocks the core. Diagnosis comes down to ruling out, one by one, the configuration, the routing and the environment.
Xray Core critical error — An “Xray Core critical error”, or “core startup error”, means the Xray-core engine that Happ uses to connect did not start or crashed. The core receives a ready configuration from Happ and stops if the configuration contains a mistake or a required resource is unavailable.
What the error means
Xray Core critical error
Text based on user reports
The Happ documentation does not describe this error, so the analysis is based on how Xray-core is built. The core validates the configuration strictly at startup and does not try to keep running with a mistake in it.
The configuration is made of three parts: the server parameters, the routing profile with geo files, and local settings such as ports and the connection mode. A failure in any of them looks the same.
So check in turn: another server, routing turned off, free ports and the antivirus. After each step, try to connect again.
Causes
| Cause | Likelihood | How to check |
|---|---|---|
| An incorrect server configuration: a syntax error in the JSON configuration that Happ passes to the core unchanged, or a wrong value in the link parameters. | High | Connect to another server of the same subscription or to a server from a different link. If the error appears on one server only, the problem is in its configuration. |
| Parameters the current core version does not support: outdated ciphers, new transports or settings introduced in a newer Xray-core. | Medium | Look at the installed version number and compare it with the releases on GitHub. In Happ Desktop 4.1.1, profiles with unsupported ciphers began to be filtered out before connecting, with a clear message. |
| A geo file problem: a routing rule refers to a geosite or geoip category that is missing from the loaded file, or the file is damaged. | Medium | Check whether the routing profile has a red exclamation mark, and connect with routing turned off, for example with the link happ://routing/off. |
| A port conflict: the local SOCKS5 and HTTP ports that the core opens are already used by another program, for example another proxy client. | Medium | Close other proxy clients and check which process listens on the port. On Windows, netstat -ano shows this. |
| The antivirus blocks or deletes the core files because it treats a network tool as suspicious. | Low | Open the antivirus log. If it has entries about files from the Happ folder, restore them and add the folder to the exclusions. |
| A bug in a specific app version, for example a startup crash with a custom noise packet in the fragmentation settings, fixed in Happ Desktop 4.4.6. | Low | Remove non-standard fragmentation and noise settings and update Happ. If the error disappears, they were the cause. |
How to fix it
Reconnect and restart Happ
Disconnect, close the app completely and open it again. A one-time core failure after sleep or a network change often does not repeat.
Result: The connection works, or the error appears again, in which case move on to the next step.
Try another server
Connect to another server of the same subscription and, if you have one, to a server from a different subscription.
Result: You know whether the error is tied to one configuration or occurs on any server.
Turn off routing
Temporarily turn off the routing profile, for example with the link happ://routing/off, and connect again. Changes apply at the next connection.
Result: The core starts without routing, which means the cause is in the profile or the geo files.
Remove non-standard fragmentation
If you set the fragment or noises parameters by hand, restore the values from your provider or delete them.
Result: The core starts with the standard ClientHello splitting settings.
Free the local ports
Close other proxy clients and programs with a local proxy. If the port is permanently busy, change the SOCKS5 or HTTP port in the Happ settings.
Result: The port is free and the core opens it without an error.
Check the antivirus
Look at the antivirus log and restore the Happ files from quarantine if they are there. Add the app folder to the exclusions.
Result: The Happ files are in place and the antivirus does not block the core startup.
Update or reinstall Happ
Install the latest version. If the error does not go away, uninstall the app and install it again, after saving your subscription links.
Result: The current version with a fresh Xray-core engine is installed, and the connection works.
Diagnostic checklist
- Another server was tested
- Routing is temporarily turned off
- Non-standard fragment and noises settings are removed
- Other proxy clients are closed and the ports are free
- The Happ files are not in the antivirus quarantine
- The latest Happ version is installed
Platforms
The error occurs on these platforms: Windows, macOS, Linux, Android.
- Xray core error in Happ on Windows
- Xray core error in Happ on Android
Key takeaways
- A core error happens before the connection is established: Xray-core did not accept the configuration or could not open a required resource.
- Happ passes JSON configurations to Xray-core unchanged, so any mistake in them leads straight to a core failure.
- A routing rule with a geosite or geoip category that is missing from the loaded file stops the core from starting.
- A local SOCKS5 or HTTP port already used by another program causes a core startup error.
- Happ Desktop 4.4.6 fixed a startup crash caused by a custom noise packet in the fragmentation settings.
Frequently asked questions
What is Xray Core in Happ?
Xray-core is an open-source network engine that does all the work with the VLESS, VMess, Trojan, Shadowsocks and other protocols. Happ is a graphical client on top of it: it stores subscriptions, builds the configuration and manages the connection. When Happ reports a core error, the failure happened in Xray-core itself, not in the app interface.
How is a “core startup error” different from an “Xray Core critical error”?
In meaning it is one problem: the core did not start or ended abnormally. Users meet both wordings, and neither message has an official breakdown. The diagnostic methods are the same: check the server configuration, the routing, the local ports, the antivirus and the app version. If your message reads differently, write it down word for word: your provider and support will need it.
Why does the core error appear on only one server?
It means the core does not accept the configuration of that particular server. It may contain a parameter your Xray-core version does not support, such as an outdated cipher or a new transport. Update the subscription and the app. If the error stays, tell your provider the server name: the configuration has to be fixed on their side.
How do I check a JSON config without exposing my keys?
Check the syntax in an editor with JSON highlighting on your own computer: it will show an extra comma, an unclosed bracket or a missing quote. Do not paste a configuration with a UUID and keys into online validators. If the syntax is correct, the problem is in the parameter values, and it is best solved with the author of the configuration.
Does switching between TUN mode and system proxy help?
Sometimes. If the error occurs in only one mode, the cause is more likely the environment, such as a busy port or a network driver, than the server configuration. If the core crashes in every mode, look for the mistake in the configuration, the routing or the app version. Compare the modes on the same server.
Can a core error be related to the provider's subscription?
Yes. A provider can deliver a routing profile in the subscription with categories that are missing from the geo files, or a configuration with parameters meant for a newer core version. Turn off routing and update the app. If everything works after that, tell your provider which part of the subscription causes the failure.
Topics mentioned
Related articles
Related sections
Sources
- Happ documentation: routing — accessed September 27, 2026
- Happ documentation: link and parameter examples — accessed September 27, 2026
- Happ documentation: local network connections — accessed September 27, 2026
- GitHub: Happ Desktop releases — accessed September 27, 2026
- GitHub: Happ Desktop 4.4.6 (pre-release) — accessed September 27, 2026
- GitHub: Happ Desktop 4.2.1 — accessed September 27, 2026
- GitHub: Happ Desktop 4.1.1 — accessed September 27, 2026
- GitHub: Happ for Android releases — accessed September 27, 2026
- Microsoft: netstat — accessed September 27, 2026
- Microsoft: Virus and Threat Protection in the Windows Security App — accessed September 27, 2026
- Android Developers: VPN — accessed September 27, 2026