Node HandbookNODE HANDBOOK中文
Hiddify · Linux desktop

Hiddify "Bad state: exit status 127" on Linux

127 is the shell saying a command was not found, not Hiddify saying your node is dead. Which fix applies depends on how far start-up got: no privilege prompt, a prompt then a missing shared library, or a core that ran and rejected the configuration.

Node Handbook editorial team ·

Scope: this page covers one situation only — the Linux desktop build of Hiddify, after you click connect and approve the VPN/TUN authorisation, fails with Unexpected failure: Bad state: exit status 127. The number means the process Hiddify tried to start did not start properly. It does not by itself prove that a node, a subscription or a specific file is broken. If the subscription updated and the node list is empty, read the subscription checks instead; if the tunnel connects but pages do not load, read the connection checklist.

Find out which stage failed before touching anything

The same dialog appears at four different points in the start-up sequence. The stage decides what you are allowed to conclude.

What you observeCheck firstWhat you cannot infer yet
No node in the configuration, connect never clickedSubscription fetch, parsing, current profileNothing about TUN start-up
Clicked VPN/TUN, no authorisation prompt appearsWhether the desktop privilege helper exists; app logThat hiddify-core.so is missing
Authorisation prompt appeared, then exit status 127Helper process, dynamic library path, start-up logThat the node is dead because of the 127
Log shows ./lib/hiddify-core.so: cannot open shared object fileInstallation package and relative library pathThat changing subscription or node can fix a start-up failure
Tunnel started, only web pages failEgress, DNS, routing, capture scopeNothing — this is not the start-up error on this page

What the public issues actually say

Issue #2411 in the Hiddify repository reports the same error on Debian. The maintainers first suggested checking pkexec and the desktop environment, because 127 can also come from the privilege-elevation command not being found. Treat that as one diagnostic branch, not a verdict for every machine.

The linked Issue #2423 adds a more specific Debian 5.2.1 case: the authorisation window did appear, but the ./lib/hiddify-core.so referenced by HiddifyCli could not be found in that start-up working directory. #2423 was folded into the still-open #2411. As of this check there is no official conclusion showing that every distribution or every newer package shares that cause.

Check in this order; do not edit system files first

  1. Save a recovery point. Record the distribution and version, the desktop environment, the Hiddify version, the package type (.deb, AppImage, and so on), the time you triggered it, and the earliest error line. Keep the existing configuration, turn VPN/TUN off, and confirm plain direct networking is back. Mask subscription URLs, keys, node addresses and account details in any log or screenshot you keep.
  2. Check the authorisation stage. If no prompt appeared at all, check whether pkexec is installed and whether the desktop environment can display a privilege dialog. Running command -v pkexec in your own terminal only reports whether the executable exists; it grants nothing. If the prompt did appear and you completed it, move on to the helper process and the library file — do not retype the password repeatedly.
  3. Read the earliest start-up error. Look in the app log for HiddifyCli, exit status 127 and hiddify-core.so. Only when the log shows the shared library failing to open do you go to the next step. A connection timeout or DNS failure belongs to the generic connection checks.
  4. Inspect the installation read-only. Only when the log points at ./lib/hiddify-core.so, check your own package type, the actual start-up file location, and whether the library exists there. A relative path also depends on the process working directory, so an absolute path copied from an issue does not describe your machine. AppImage and .deb organise their files differently — do not copy another user's path, and do not modify the binary or system directories first.
  5. Verify the package against the official channel. Hiddify's official Releases publish different packages per system, including .deb and AppImage. Note your current version and package, then check whether a build for your system — or a reinstall note for the same version — exists. Do not download a so-called fixed build from an unfamiliar file host, and do not delete the whole application data directory without evidence.
  6. Re-test the same action. Change one variable at a time: the package, or the way you launch it. Record whether the prompt appeared, whether the 127 disappeared, whether the core started, and whether a plain HTTPS page loads. The 127 disappearing only means this start-up stage passed; it does not prove the node stays usable.

Why the commands inside the issue are not a general fix

The reporter in #2423 used patchelf to rewrite the binary's reference, and mentioned changing permissions or creating a /root/lib link. Those are temporary measures inside one environment. They touch system files and executable capabilities, and they are overwritten by the next update. This page does not present them as repair steps. Keep the evidence first, then use the official packages and the maintainers' feedback channel; if a maintainer publishes a fix note for your version, follow that note.

What to include when you file an issue

Write down the distribution and version, the desktop environment, the package name, the Hiddify version, whether the authorisation prompt appeared, the output of command -v pkexec, the real installation location, and the earliest error with secrets removed. If the log mentions hiddify-core.so, attach only the relevant lines. Do not upload a full subscription, node configuration, system user name, or an unredacted log. That is what lets a maintainer separate the privilege helper never started from the helper started and then could not find the shared library.

Sources and limits

  • Hiddify Issue #2411 — the still-open main report of Linux exit status 127, including the maintainer suggestion to check pkexec. A single case does not represent every system.
  • Hiddify Issue #2423 — a Debian 5.2.1 .deb report about the relative library path, merged by the maintainers into #2411. The reporter's temporary workaround was not adopted as an official general solution.
  • Hiddify official Releases — used only to match your system to a package and version, not to conclude that 127 is fixed.

This site has not reproduced the error on every Linux distribution, and has not verified whether the newest packages fix this particular path. What the page provides is a way to narrow down the failing stage using public evidence.

127, 126, 1: three different layers

On Linux, Hiddify starts the core as a child process. The exit status in the log is that child's exit code, not an error code of Hiddify's own. The three numbers point at three unrelated causes, so separating them first removes most wasted work.

Exit codeWhat it actually meansCheck first
exit status 127The program to execute was not found, or its dynamic linker is incompleteWhether the executable path in the log exists and is executable
exit status 126The file was found but is not executablePermission bits and mount options, including noexec
exit status 1The program ran and decided to failThe first core log line after it — usually configuration or the network interface

exit status 127: the program was never executed

127 is the shell's "command not found". In the Hiddify case it is usually not a wrong configuration field: the bundled HiddifyCli or the core binary did not land at the path the log shows. Copy commands quoted in issues come from one specific package layout; pasted into a different installation method (AUR, Flatpak, a third-party deb), they often point at a directory that does not exist — and the error turns from "invalid configuration" into 127.

The log also says error while loading shared libraries

This is frequently misread as "the file does not exist". In fact the binary was found, but a dynamic library it depends on is missing, so the loader fails first and the outer process only sees 127. What to check at that point is the library name and the glibc version — not another copy of the executable.

exit status 126: file present, no permission to run

126 usually appears when permission bits are lost during unpacking, or when the program sits on a mount point with noexec. Run ls -l for the permission bits, then look at the mount options. Before adding executable permission recursively to a whole directory, confirm what else is in that directory.

exit status 1: the core started, the problem is configuration or the interface

This is the only one of the four where the program actually ran. The cause is in the core log immediately after it: a refused TUN device creation, a routing table conflict, or a configuration field the current core version rejects. Do not keep looking at executables here — check the configuration against the unknown field path instead.

Which log lines to attach

Keep at least three: the version and core path printed at start-up, the full core output around the failure, and uname -r plus the installation method. Posting only the last exit status line leaves a maintainer unable to tell packaging from permissions from configuration — which is why similar issues keep asking for the same details.

Common questions

Does exit status 127 mean the subscription link is broken?

No. The error on this page happens during VPN/TUN start-up. First confirm nodes already appear in the configuration, then look at the authorisation and helper log. An empty subscription goes to the subscription checks.

The password dialog appeared — do I still need to check pkexec?

You can note whether it exists, but prioritise the first error from the helper after authorisation. #2423 found the shared-library path problem precisely in a case where the authorisation window did appear.

I see no shared-library error. Does that mean the node is fine?

No. The absence of that line only means #2423's specific case does not apply yet. Check configuration, routing, DNS or egress against the error you actually have.

Can AppImage users copy the install path from a .deb report?

Not directly. Verify your own package and real start-up path first, then decide from your own log whether you are in the library-loading branch.

Can I just launch the whole GUI app with sudo?

Not as a routine fix. It can change ownership in your home directory and in the application data. Treat it as a diagnostic question a maintainer may ask about a specific environment, not as a long-term way to run the client as administrator.

Will upgrading to the newest version definitely fix it?

Not guaranteed. Record the same action and error before and after the upgrade, read the release notes and the still-open main issue, and do not treat a version number as proof of a fix.

Related

Hiddify and Clash error index · Hiddify WARP: parsePrefix empty IP · Error index · Subscription converter