Skip to content

Troubleshooting ​

Find the code or the words on your screen in the section named after the place they appear; each row gives the cause and the fix. In the tables, <hub> stands for the address of the machine that runs the hub.

The panel is unreachable ​

SymptomCauseFix
the browser reaches nothing at http://<hub>:8080the panel's unit is down, the port moved, or this network is not exposedrun systemctl status neutrino_hub_web on the hub, then read Panel ports and Exposure on Network
http://<hub>:8080 moves to https://<hub>, which reaches nothingHTTPS is on, so the HTTP port sends every browser to the HTTPS port, and that port is unreachable from hereread HTTPS port under Panel ports on Network, and check that the port is open on the way to the hub
the session ends after a panel port changedthe panel restarted on the new port, and the session cookie is named after the port, neutrino_session_<port>sign in again at the new address
the session ends after Enable HTTPS or Disable HTTPSthe switch ends the session, and the port you left deletes the cookie when it sends you onsign in again at the address the page moved to
after Disable HTTPS, signing in over http:// comes back to the login cardthe browser kept the Secure cookie from the HTTPS port and keeps it over the new oneselect Clear the old session on the login card, or open the https:// address one time, which sends you back with the cookie removed

The browser warns about the certificate ​

These rows apply to the HTTPS port. The hub's own certificate authority signs its certificate, and a browser trusts that authority only after it is installed there and the browser restarts.

SymptomCauseFix
the browser says the certificate authority is not trustedthe authority is not installed on this deviceopen http://<hub>:8080, select Install certificate under Settings > HTTPS, follow the steps for this device, and restart the browser
Enable HTTPS is greyed and the line beside it reads Install the certificate, then restart the browser.this browser rejected the HTTPS port's certificateinstall the authority for this system, restart the browser, and open the http:// address again
Chrome shows Not secure after the authority was importedChrome was told to proceed past a certificate warning before the importrestart Chrome
Firefox warns and Chrome on the same machine does notFirefox keeps its own list of authoritiesfollow the Linux, Firefox steps under Install certificate
every browser warns again after a change on SettingsRegenerate certificate made a new authorityinstall the new authority on each device and restart the browser; http://<hub>:8080/api/hub/setting/https/authority serves it while HTTPS is on
the browser says the certificate is for another namethe address in the browser is missing from Certificate names, as a public address always isopen the panel at a name or address listed there, such as hub.neutrino.internal on the LAN

Locked out ​

SymptomCauseFix
Locked after repeated failures.too many wrong passwordsrun sudo nhub unlock on the hub; it also lifts every fail2ban SSH ban
Wrong password. and it is forgottenthe panel password is lostrun sudo nhub reset password on the hub; every session is signed out
the vault passphrase is lostthe running hub still reads the vault with its own working key; a backup taken under the lost passphrase stays sealedrun sudo nhub vault rekey on the hub to set a new passphrase, then download a new backup
vault_locked, on a client's row or a module, or Vault locked on the SSH Relay cardthe box has no working copy of the vault's data key, so nothing stored in the vault opensrestore a backup under Settings with its vault passphrase; the restore writes the working copy again

The Credentials page rejects a key ​

SymptomCauseFix
key_is_publicthe pasted key is a public keypaste the private key, with its BEGIN and END lines
key_passphrase_neededthe private key is encryptedfill Key passphrase with the key's passphrase, then save again

Restoring a backup fails ​

With any of these codes, nothing is restored.

SymptomCauseFix
backup_wrong_extensionthe file is not a backup this panel writespick the archive that Download backup saved
backup_corruptthe archive is damageddownload the backup again, or pick an older one
vault_passphrase_wrongthe passphrase does not open this backuptype the passphrase that was set when the backup was taken
backup_mode_unavailablethe backup sets a mode this hub does not offer, such as a side gateway on the mainland editionrestore it on a hub of the full edition, on Linux
the restore's apply stops shortthe files are restored, and one step of the apply failedfix the cause the dialog names, then run sudo nhub apply on the hub

A device is offline ​

SymptomCauseFix
agent_offline, in the panel or on a client's rowthe machine's agent is not connected to the hubon the machine, run sudo nagent status; when it reads the service as stopped, run sudo nagent start
the machine is listed and its modules cannot be changedan offline machine rejects every change, and nothing is queuedbring the machine back, then apply again

A program is turned away by the hub ​

An agent shows these codes in nagent status. A client shows them as words on its hub row, listed under The state line of a hub row.

SymptomCauseFix
protocol_too_oldthe program is a 0.3 or 0.4 package, which speaks an older protocol than a 0.5.2 hub acceptsinstall the 0.5.2 package on that machine, which nagent --version confirms, and join with a new link. A 0.4 hub cannot be upgraded to 0.5.2: remove it and install 0.5.2 fresh, as Settings describes
protocol_too_newthe program speaks a newer protocol than the hubupdate the hub under Settings; the binding stays and the program connects again
hub_untrustedthe hub was reset or installed again, and its certificate changedjoin again with a fresh link, from Add by link on Devices for an agent and from Clients for a client
binding_unknownthe machine's row was removed on the hub's Devices or Clients page, and the program deleted its bindingjoin again with a new link

Joining a hub fails ​

SymptomCauseFix
link_not_for_client or link_not_for_agentthe link is for the other kind of program: Clients makes client links, Devices agent linksmake a link on the right page
link_unreadablethe pasted link is cut offcopy the whole link again
ticket_spentthe link is used, older than 30 minutes, or replaced by a newer link of the same kindon a client, select Leave on the row; then join with a new link
admission_pausedthe hub paused joins after too many failed onesleave the client running; it joins again after the seconds the code names
unsupported_remote_install, in the Install agent dialog on Devicesthe machine reports a system other than Linux, and the SSH installer is for Linuxinstall the agent on the machine itself and join it with a link, as Install an agent describes

The state line of a hub row ​

The client window and the Android app show these words under a hub's name. A countdown runs live, and at 0 the line reads Connecting… again.

SymptomCauseFix
Connecting… for a long timethe client is dialling every address of the hub, and a dial waits out its connect timewait for the round to end; the line then names a reason
The hub did not answer · retrying in 5 sno address of the hub answered, and the device is not on the hub's virtual networkcheck that the hub runs and that the device reaches one way in, then select refresh
The hub is not on the virtual network · retrying in 5 sno address answered while the device is on the hub's virtual networkcheck the hub's badge for that network on its Access page
No networkthe device has no network at allconnect the device to a network; the client dials when one comes up
Certificate mismatch · retrying in 60 sthe certificate at the hub's address differs from the one the link pinnedafter a reset or a new install of the hub, select Leave and join with a new link
The hub pauses new devices · retrying in 60 sthe hub paused joins after too many failed onesleave the client running; it joins again when the countdown ends
The hub does not know this devicethe hub's Clients page no longer lists this clientselect Leave, the row's only button, then join with a new link
Version too oldthe client and the hub speak different protocol numbersupdate the older of the two, then select refresh
Join refused · and the reasonthe hub rejected the link's ticket, as for a link used already, expired, or replaced by a newer link of the same kindselect Leave, then join with a new link from Clients
Replaced by another client · Reconnectanother client connected to the hub as this oneselect Reconnect to take the hub back
Disabled by the hubthe client is switched off on Clients, and every action returns client_disabledselect Enable on its row there; the line changes by itself

The client does not connect ​

SymptomCauseFix
hub_unreachableport 8443 on the hub is unreachable from this computercheck the network, the ways in on Access, and Exposure on the hub
gui_webkitgtk_missingWebKitGTK is absent on Linuxinstall the packages the message names, then start the client again
gui_webview2_missingWebView2 is absent on Windowsinstall the runtime the message names, then start the client again
root_refusedthe client was started with sudostart it from your own account
client_heldanother account's client runs on this computerquit the client in that account, or sign that account out, then start yours

The virtual network does not connect ​

These show on a hub row's Virtual network line, in the desktop client and in the Android app. The client tries a failed connect only when you select Connect again.

SymptomCauseFix
Connecting… with This machine is registered with the console. Attach it to a network there.in console mode, the console has not attached the device to a network yetattach the device to the hub's network in the EasyTier console, as EasyTier describes
overlay_join_failed, with the engine's own words after itNetBird or EasyTier rejected the join; with NetBird, the hub often holds a one-time setup key already spentcreate a reusable key in the NetBird console, paste it with Replace on the NetBird card, then select Connect again, as NetBird describes
overlay_other_networkthis device is on another NetBird network or on another hub's virtual networkon the other hub's row, select Disconnect on its virtual network line, then connect this one
overlay_daemon_downthe NetBird or EasyTier service on this computer is stoppedreinstall the client
bundle_missingthis install has no NetBird or EasyTierreinstall the client
overlay_no_addressthe engine gave the device no address within 90 secondscheck the device's own network, then select Connect again
overlay_console_invalidEasyTier cannot use the console address the hub namedcorrect the console address on the hub's EasyTier card and apply
overlay_withdrawnthe hub no longer publishes that network to this clientturn the network on again on the hub's Access page, or add the virtual network to the client's permission on Clients

Access ​

SymptomCauseFix
turning an engine on, or saving an EasyTier address, is rejected with overlay_subnet_overlapthe engine's network overlaps the other engine's or a network the hub holds an address onchange EasyTier's This box's address or the LAN's address on Network; NetBird's network is always 100.64.0.0/10
the Access page shows overlay_default_route_refused in reda peer or the console gave the hub a default route through the network, and the hub deleted itremove the exit route for the hub in the NetBird or EasyTier console; the hub keeps its own uplink as the way out
overlay_route_overlap with The hub cannot take it awaya route on the network overlaps one of the hub's networks, and the hub could not deselect itchange or remove that route in the NetBird or EasyTier console
direct_host_invalidPublic address under the Direct card is neither a host name nor an IP addresstype a host name or an IP address, then select Apply access
easytier_config_server_invalidthe pasted text is neither a console address nor a tokenpaste the whole address after --config-server, of the form tcp://host:22020/token
easytier_invalidManual bootstrap peers is chosen and no bootstrap peer is listedadd at least one bootstrap peer, then apply again
the hub does not respond on a virtual networkthat network is not in Exposuretick it under Exposure on Network
NetBird's badge reads not joinedthe hub has no NetBird identity, or its last login expiredjoin again with a new setup key
NetBird's badge reads management unreachablethe hub cannot reach NetBird's management serveron the hub, check the uplink, that DNS resolves the management server's name, and the management URL
NetBird's badge reads not runningNetBird is stoppedturn the card on and select Apply access
NetBird's Peers is emptyno other device has joined the networkon a client, select Connect on the hub row's virtual network line
a client reaches the hub over NetBird and the hub's LAN devices stay unreachablethe console has no access policy for the LAN routeadd the network and its policy in the NetBird console, as LAN devices over NetBird describes
EasyTier reads No machine has joined yet.the other machine's network name or secret differscopy the command again with Copy with the secret
a device joins over EasyTier and the hub's LAN devices stay unreachablethe LAN subnet is not routed on the networkin manual mode, add the subnet under Exported networks and apply; in console mode, add it as a subnet proxy in the console, as LAN devices over EasyTier describes
the SSH Relay card's Status reads Not configuredServer, Account, or the key or login is empty or gonefill in the settings and select Apply SSH Relay
Authentication failedthe server rejected the key or the passwordcheck the key's line in the account's authorized_keys, or the password and PasswordAuthentication
Forward refusedthe server refused the listener, or another program holds the portcheck that permitlisten names the Public port, and free the port on the server
Public port closedthe forward runs, and the public address returns no answer or another certificatecheck GatewayPorts clientspecified, the provider's firewall and the server's firewall
Host key changedthe server presents a key other than the one recordedif you replaced or reinstalled the server, select Forget host key
Server unreachableSSH could not reach the server, or the connection droppedcheck Server and SSH port, and that the server is up

Network settings are refused ​

SymptomCauseFix
network_invalid with the field role: the panel reads that the port cannot answer with the role Disableda port ticked under Exposure has the role Disabledgive the port the role WAN or LAN, or untick it under Exposure, then apply again
Country code reads Two letters, such as DE. 5 GHz needs one., or network_invalid with the field country_codean access point on 5 GHz has no valid two-letter country codetype the code of the country the hub is in under Country code, such as DE, then apply again
port_out_of_range, on the Network, Access, Proxy or Settings pagea port field holds a number outside 1 to 65535type a port from 1 to 65535, then apply again
port_already_in_useanother program on the hub's computer already listens on that portpick another port, or stop the program that holds it
resolver_required, on the Proxy pagethe Remote resolvers (proxied names) list is emptyadd at least one resolver, then select Apply route

Errors on the Modules page ​

A tab of the Modules page shows these codes under its state word or on a row, and a refused apply names one.

Every module ​

SymptomCauseFix
module_fetch_failed, with the download's own words after itthe hub could not download the module's install filecheck that the hub reaches the internet, then select Install again
a module is greyed with This machine's system cannot run it, or no_platform_buildthe module has no build for this machine's systempick another machine; Supported platforms lists each module's systems
gitea_git_missinga Mac or a Windows machine has no usable git for Giteainstall git, then select Install again

Instances of VS Code, code-server, CloudCLI and Codeg ​

These codes also come from the Terminal tab and from the accounts under Global configuration.

SymptomCauseFix
account_unknownthe machine has no account by that nametype the name of an account that exists on the machine, or create it there
account_invalidthe name cannot be an account name on that machinetype a valid account name
account_duplicatetwo instances name the same accountremove one of them
port_duplicatetwo instances use the same portgive each instance its own Port
port_invalidthe port is outside 1024 to 65535type a port in that range
credential_missinga Windows instance has no login pickedpick the account's login under Windows login for the account
credential_invalidWindows no longer accepts the instance's login, as after a password changeadd a login with the new password on Credentials, pick it, and apply again
token_missingthe hub sent no connection token for the instanceapply the module again
secret_missingthe hub sent no token secret for a code-server or Codeg instanceapply the module again

CloudCLI ​

SymptomCauseFix
cloudcli_node_download_failedNode.js for CloudCLI could not be fetched or unpackedcheck that the machine reaches the internet, then select Apply CloudCLI
cloudcli_npm_install_failednpm failed to install CloudCLI for the account; the row shows npm's last linesfix what npm's lines name, then select Apply CloudCLI
cloudcli_native_module_failedbetter-sqlite3, node-pty or bcrypt could not fetch its prebuilt binarycheck the machine's internet access, then select Apply CloudCLI
cloudcli_install_out_of_memorythe machine ran out of memory during the npm installfree memory on the machine, then select Apply CloudCLI
cloudcli_port_takenanother program on the machine holds the instance's portchange the instance's Port, then apply again
cloudcli_register_failedthe account's CloudCLI already has an administrator with another passwordwait: the agent starts that CloudCLI afresh with a new sign-in file, then signs in again every 30 seconds until it succeeds

Codeg ​

SymptomCauseFix
codeg_download_failedthe server bundle or the Node.js archive did not reach the machine from the hub, or did not unpackcheck the hub's own download first, then select Install or Apply Codeg again
codeg_port_takenanother program on the machine holds the instance's portchange the instance's Port, then select Apply Codeg

VS Code ​

SymptomCauseFix
terms_not_acceptednobody accepted Microsoft's terms for VS Code on this machineselect Open and accept the terms on the VS Code tab

code-server ​

SymptomCauseFix
code_server_download_failedthe release could not be fetched or unpackedcheck that the machine reaches the internet, then apply again
code_server_port_takenanother program on the machine holds the instance's portchange the instance's Port and select Apply code-server again

Remote desktop ​

The tab, the device's drawer on Devices, and a client's Connect show these codes. Apply remote desktop tries a failed step again.

SymptomCauseFix
rdp_takeover_faileda step of starting the agent's RustDesk failed; the code names the stepfix what the step names, then select Apply remote desktop
rdp_restore_faileda step of putting back the machine's own RustDesk failedfix what the step names, then select Apply remote desktop
rdp_nobody_seatednobody is signed in at the machine's screensign in at that machine's own screen
rdp_screen_not_alloweda Wayland session has not allowed screen sharingallow screen sharing one time at that machine's own screen
rdp_permissions_neededthe Mac has not given RustDesk Screen Recording and Accessibilitygrant both to RustDesk in that Mac's System Settings > Privacy & Security

Terminal ​

SymptomCauseFix
path_invalidthe shell program is not a full pathtype the program's full path, or pick it with Browse…
shell_program_unusablethe program is missing on the machine, or it cannot run; for nclient terminal exec, the command's programpick a program that exists and runs, or clear Shell program; for exec, check the command's name or path

AI tools ​

SymptomCauseFix
switch_failedcc-switch could not point the account's tools at the gatewayread the words on the account's row, then turn the setting off and on
cc_switch_download_failedthe machine could not get cc-switch from the hubcheck that the hub reaches the internet, then turn the setting off and on
cc-switch did not put the tools back to their own settings: and cc-switch's wordsthe switch back failed, and the control stays onfix what cc-switch printed, then select the control again

A client page cannot reach its service ​

The hub or the agent of the providing machine returns these codes, and the client shows them on the entry's row.

SymptomCauseFix
connect_failed with refusednothing listens on the service's port on that machinestart the service, or the module, on that machine
connect_failed with timeoutthe service did not respond within 10 secondscheck that the machine and the service are up
connect_failed with unreachablethe hub has no route to a service declared by hand on Servicescheck the declared address, and that the hub's LAN reaches it
port_not_publishedthe machine stopped publishing the port: the container, the instance or the share stoppedstart it again on the Modules page
connect_limitthe client has 256 connections open through the hubclose forwards or programs the client does not need
permission_deniedthe client's permission on Clients leaves out that kind of entry, that machine, terminals, remote commands or the panelwiden the client's permission on Clients
service_unknownthe hub no longer publishes the entryselect refresh; the entry leaves the list
port_takenanother program on this computer listens on the entry's Fixed local portselect Configure on the row and pick another port
web_token_missingthe hub sent no token for a VS Code, code-server or CloudCLI entryselect Open again

A share does not mount on a computer ​

SymptomCauseFix
mountpoint_invalidthe path is outside your homegive a folder under your home, such as ~/nas/media
mountpoint_not_drive_letterWindows mounts a share at a drive letterpick an unused letter, such as N:
mountpoint_not_emptythe folder holds filespick an empty folder
mountpoint_in_useanother entry, from any hub, mounts at that pathpick another folder or drive
mount_not_authorizedthe polkit prompt or the macOS login dialog was dismissed. On Linux, polkit rejects the mount without a prompt when the client was started outside a desktop session, such as from an SSH loginselect Mount again and confirm the prompt. Outside a desktop session, quit the client and start it from the desktop, or with systemd-run --user nclient gui
mount_tooling_missingmount.cifs or the client's mount helper is absentinstall the client package again, which depends on cifs-utils
pkexec_missingthe computer has no pkexec, which a mount on Linux goes throughinstall the pkexec package, then select Mount again
mount_timed_outon macOS, the system did not finish the mount within ten minutesselect Mount again
credentials_missingthe saved credentials file is goneselect Configure and type the password again
share_login_rejectedthe share rejected the username or the passwordselect Configure and enter both again
share_access_deniedthe share accepts the login and denies that account accesspick the user under Who may use it for that share on the Modules page
share_not_foundthe host has no share by that namecheck the share on the Modules page or on Services
share_session_conflictWindows holds a connection to that server under another logindisconnect that connection in Windows, then select Mount again
files_adapter_unavailable on Windowsthe NeutrinoClientFiles service is missing, stopped or failing, so the files adapter could not startread the words after the code, run sc query NeutrinoClientFiles, and install the client again if the service is missing
files_adapter_in_use on Windowsanother account's client holds the files adapterquit the client in that account, or sign that account out; the mount runs again after that
the row is greyed, Not reachable nowthe serving machine is off or not connected to the hubbring the machine back

A computer shows share_unreachable for the same causes as a phone, listed in the next section.

A share is unreachable on a phone ​

The Files app on the phone shows the Android app's shares, and reports a failure as the code's sentence.

SymptomCauseFix
share_unreachable, with the hub's row not Connectedthe device cannot reach the hub's port 8443bring the hub's row to Connected through any way in on Access: the LAN, NetBird, EasyTier or the SSH Relay
share_unreachable while the hub's row reads Connectedthe machine that serves the share is off or not connected to the hubbring the machine back
Files reads Give this share's password on the Files screen first.the share has no login on this phone yetopen the share on the app's Files screen, enter the username and password, and select Connect

A terminal closes ​

SymptomCauseFix
session_not_ownedthe session belongs to another viewer and is not shared, or persist or share was asked by a client that did not open itask its owner to switch on Shared, or open a terminal of your own
session_unknownthe session ended, or the agent restarted or updated, which ends every session on that machine, or the id given to attach, persist, share or stop matches no sessionopen a new terminal on the machine
shell_unknownthe hub no longer holds the shell the client resizedclose the terminal in the client and open it again
unknown_terminalthe hub offers no terminal on that machine, or nclient terminal named an unknown machinepick a machine the client's Terminals page lists

A remote desktop does not open ​

A code about the sharing machine's screen, such as rdp_nobody_seated, is under Remote desktop.

SymptomCauseFix
the page reads No shared remote desktops yetno machine is sharing, or the sharing machine is offlineturn on Share this machine's desktop on that machine's tab
rdp_viewer_opena viewer is already open on that desktop from this clientclose the open viewer, then select Connect again
rdp_not_sharedthe machine stopped sharingturn the share on again on that machine's Remote desktop tab
rdp_no_desktopthis session has no screen to open a viewer onconnect from a desktop session
rdp_launch_failedthe viewer did not start, with the reason after the codefix the reason, then select Connect again

An AI tool ignores the gateway ​

SymptomCauseFix
no_endpointthe hub has issued this client no keyon the hub's AI page, revoke the client's key so a new one is issued, or join the client again
no_exit_hubthe switch was turned on for a hub that is not connectedwait until the hub's row reads Connected, then turn the switch on
the tools keep their own configuration after Save in AI tool configurationSave keeps the model choices and points nothingswitch on The AI tools use this gateway on the entry's row; nclient service ai show prints where the tools point
the panel reads gateway_unreachablethe gateway process is downrun systemctl status neutrino_hub_cliproxyapi on the hub
a tool reaches nothingthe tools point at the client's forward on 127.0.0.1, which listens only while the client runsstart the client, or keep it running in the tray
login_expireda subscription sign-in on the AI page took too longselect Try again and finish the sign-in in the browser
the client's AI page is greyed with ai_tools_managed's sentencethe Neutrino agent is installed on this computer, and it sets the AI toolsset the AI tools on the hub's Modules page, under Global configuration for this machine

Where the logs are ​

WhatWhere
the setup runsetup.log in the hub's log directory, /var/log/neutrino/hub/setup.log on Linux
the hub on Linuxeach unit's journal: journalctl -u neutrino_hub_web -n 200, and likewise neutrino_hub_xray, neutrino_hub_dnsmasq, neutrino_hub_cliproxyapi, neutrino_hub_netbird, neutrino_hub_easytier, neutrino_hub_relay
the hub on macOS and Windowsone <name>.log per process in /Library/Logs/Neutrino/hub/ on macOS and C:\ProgramData\Neutrino\hub\log\ on Windows
a hub updatejournalctl -u neutrino_hub_update on Linux; hub_update.log in the hub's log directory on macOS and Windows
the agent on Linuxjournalctl -u neutrino_agent -n 200 on that machine
the agent on WindowsC:\ProgramData\Neutrino\agent\log\agent.log
the agent on macOS/Library/Logs/Neutrino/agent/agent.log
the desktop clientclient.log in ~/.config/neutrino/client/ on Linux, ~/Library/Logs/Neutrino/client/ on macOS, and %LOCALAPPDATA%\Neutrino\client\ on Windows
the client's EasyTier daemon/var/log/neutrino/client/ on Linux, /Library/Logs/Neutrino/client/ on macOS, and C:\ProgramData\Neutrino\client\log\ on Windows
the AI gateway, from the panelJournal on the AI page
what a render producessudo nhub apply --dry-run on the hub

Neutrino · personal developer infrastructure