Troubleshooting

If a notification shows HM-E****, look it up in Error codes for its cause and recommended action.

Check in this order

1. Record the notification details and time, then stop aggregation normally. Check whether each network works independently without HypoMux.
2. Retry the same app with other proxy, VPN, and accelerator takeovers disabled to distinguish basic connectivity from conflicts.
3. Run Network Check, select working paths, restart HypoMux, and establish new application connections. Change one setting at a time.
4. Follow the matching symptom below. If it persists, collect the report details. Do not begin by deleting settings, clearing rules, or disabling the entire firewall.

Aggregation does not improve speed

Confirm that the download makes several concurrent connections. A source using only one TCP connection remains limited by the network path assigned to that connection.

Also check that at least two working adapters are selected and that new connections are distributed across them in Connections. Source throttling, disk speed, Wi-Fi signal, and a mobile plan can all be bottlenecks.

• The app is absent from Connections: Confirm that it follows the system proxy or uses a configured local proxy. See Operating modes if it needs another capture method.
• Only one adapter receives connections: Check other adapters and whether Routing rules pin the traffic to an egress. Existing connections need to be re-established for new scheduling decisions.
• Several adapters receive connections but speed stays low: Test the paths separately, check for a shared broadband bottleneck, then compare using the same source and concurrency. Changing weights does not increase a path's underlying capacity.

An adapter cannot be added to the pool

Run Network Check and verify IPv4, gateway, DNS, and source-address binding. Adapters without an active internet connection should not be added.

Conflict with another proxy or accelerator

Disable the other program's system-proxy takeover. If it has created a TUN / VPN and taken the default route, exit it first. Then restart HypoMux and choose the mode again.

An application fails in Virtual Adapter mode

If the issue only occurs in Virtual Adapter mode, compare system / mixed / gvisor under Settings → Advanced network → TUN stack. The selection saves automatically but requires stopping and restarting Virtual Adapter mode. See TUN stack selection. Record the affected application, traffic type, and stack; change one setting at a time.

If the virtual adapter never comes up, or the whole computer loses connectivity after starting, the cause is usually a local network component rather than the stack choice. Run the network components and TUN compatibility check under Settings → Advanced network and follow its result before retrying. If strict routing and DNS leak protection is on, turn it off for one comparison run to see whether the WFP rules are involved.

Inconclusive NAT tests or P2P connection failures

Stop aggregation and select the physical adapter under Network diagnostics → NAT type detection. See NAT type detection for result meanings.

• Needs calibration / host firewall interference: Select Allow and retest on the result card and complete the firewall authorization prompt. Unlike ordinary testing, this permits UDP replies for HypoMux; you do not need to disable the entire firewall. Use the actual retest result rather than assuming a classification.
• Timeout, resolution failure, or unsupported server: Check adapter connectivity and server attempt history. Try automatic selection or another RFC 5780-capable server. A basic STUN server returning your public address may not support behavior discovery. UDP blocking or packet loss can also cause timeouts; a timeout alone does not identify the NAT type.
• Port-restricted, symmetric, or mixed behavior with actual connection failures: Test other available networks and compare the application. Check for double NAT between modem and router, or ask your ISP about shared public IPv4. If inbound access is required, assess a public address, application-specific port forwarding, or the application's relay option. Switching TUN stacks or adding adapters cannot remove upstream NAT restrictions.

When sharing results, redact public and local endpoints while retaining the NAT type, mapping/filtering behaviors, server attempt history, and test time.

An upgrade or in-place install fails

A file-in-use message, an installer that stops responding, or an old version still reported after installing usually means a leftover process, the Core service, or a read-only file was not released. Work through these steps in order:

1. Stop aggregation normally and exit HypoMux, including the tray icon. Close every unfinished installer window.
2. Run the signature-verified official installer again. See Upgrading.
3. If it still fails, use the upgrade check and repair tool in tools/support/: run Start-HypoMux-Repair.cmd, enter 1 to check the environment and produce diagnostic logs, and only then enter 2 to repair.

A few things to know about that tool:

• Elevate using the same Windows account you normally run HypoMux with. Do not enter another administrator's credentials.
• Repair requires typing a confirmation. It ends HypoMux processes at verified paths, stops Core, restores network settings using the signed program's own commands, and clears the read-only attribute on Core files. Downloads in progress will drop.
• It does not delete settings, routing rules, caches, or installed files, does not change directory permissions, does not reset DNS/Winsock, and does not disable security software. Automatic restoration only accepts programs with a valid signature published by SignPath Foundation.
• Run the official installer again after the repair. Core may stay stopped, and a reboot alone will not re-enable it, so complete the in-place install instead of deleting services or system files yourself.
• The logs can contain your Windows username and install path. Redact them before attaching, then follow the report details.

Connectivity is still broken after stopping

If HypoMux is still running, select Stop and wait for completion. After a crash, reopen it so it can attempt recovery, then exit normally and test connectivity.

For System Proxy mode, inspect Windows Settings → Network & Internet → Proxy for a reference to HypoMux's stopped local port. Record the old value before editing. Restore previous settings only after confirming that this is a HypoMux leftover, not a proxy required by your organization or another app. Do not blindly clear organization proxies, DNS, or routes.

For Virtual Adapter mode, or if ownership of a setting is unclear, preserve logs and the current state and report the issue. Avoid deleting adapters or resetting all networking before diagnosis.

Version 2.7 feature issues

Symptom	First check
AI chats but tools fail	Protocol, tool test, and pending approvals
Hotspot unavailable or no internet	TUN prerequisites and sharing status
Subscription updates do not change routing	TUN, restarts, priorities, and new connections
MTU times out or cannot apply	ICMP target and expired or changed configuration
Scheduler change has no immediate effect	Learning and new connections; established connections stay bound

Do not start the service merely to collect information. Version, page errors, and screenshots can often be collected while stopped.

Include this information in an issue

• Your HypoMux and Windows versions.
• The operating mode and selected adapter types.
• Reproducible steps and the time the issue occurred.
• Redacted logs, Network Check results, and whether a VPN, TUN, proxy, or accelerator was also running.

Copy this template into GitHub Issues, or ask the community first:

HypoMux / Windows versions:
Operating mode / scheduler (include the stack for TUN issues):
Adapter types and whether they share a broadband connection:
Other VPN, proxy, or accelerator software:
Steps to reproduce:
Expected / actual result:
Error code / time:
Does stopping HypoMux restore normal behavior?
Checks already tried:

Redact public IPs, local usernames, device names, private domains, tokens, and account details. Keep error codes and nearby log context rather than sending only a screenshot saying the app does not work.

Find support logs

Version 2.7.0 has no standalone public Logs navigation page. Under Settings → Configuration and startup → Configuration file location, open its directory and look for logs/app.log. The default data directory is .hypomux under the current Windows user's home; use the actual location shown in Settings.

Logs retain up to 3 recent sessions, with a 5 MiB total limit. Preserve the relevant time range promptly instead of repeatedly restarting. No previous session may mean no log is available; provide the error, version, and reproduction steps without starting the network service merely to create a log. Redact before sharing, and do not upload the entire settings directory or AI/hotspot credential files.