Connectivity Troubleshooting · Clash Technical Blog

Mihomo MASQUE download stalls: ip-stack

MASQUE download drops to zero while new requests still work? Check the Mihomo version and with_gvisor, compare ip-stack on the affected node, verify the same request, and keep a rollback. The report does not establish a released fix.

Read the articleBack to blog
  • MASQUE
  • Mihomo
  • ip-stack
  • gvisor
  • Single-connection stall
On this page
Published
Estimated reading time
About 8 minutes

A MASQUE node connects and a file starts downloading, but the transfer suddenly stops while newly opened pages still load. First check whether one request or every connection has stopped, then inspect the actual Mihomo version and that outbound node’s IP stack.

Is the tunnel still working when a download stops?

Mihomo #3325 is a Linux/ImmortalWrt user report: a single TCP download stops receiving data partway through, while new connections over the same MASQUE tunnel still work. The report covers alpha-bc76c13 and a self-built alpha-94b13ae; the author did not observe the same stall in their comparison using gvisor.

At the time of review, the report remains open, with no maintainer conclusion or released fix. These checks are reversible. They do not establish a defect affecting all MASQUE setups, all platforms, or v1.19.32, and switching stacks is not guaranteed to restore the transfer.

Compare existing and new connections on the same node

What you observeNext step
One download stops, but new requests still workRecord when it stopped, the data received, and the actual outbound, then compare a single IP stack setting.
Both existing and new requests fail, or MASQUE cannot connectInvestigate the configuration, node, or connection error first. The single-connection report cannot explain every loss of connectivity.
A short test works for nowKeep the observation, but it cannot rule out a problem that appears only on long connections. There is no need to increase test traffic immediately.

Check the running core and with_gvisor build support

Save an independent copy of the working configuration. Record the affected node name, its complete original ip-stack value, the actual core version, and the download request details. A graphical client version is not the core version, and another Mihomo binary in your shell may not be the one the app is running.

Here, mihomo means the executable of the running core. For an embedded client or router plugin, invoke its actual path instead of judging by another program found through the command search path. Look for with_gvisor in the version output under Use tags.

Check the running core’s version and build tags
mihomo -v

The source pinned to v1.19.32 and the reported 94b13ae source both support the MASQUE ip-stack field. In the verified implementation, an empty value becomes auto, and auto selects mips; gvisor requires with_gvisor at build time. Here, mips names an outbound IP stack, not the processor architecture for installing a core.

This comparison applies only to MASQUE configurations that use the userspace IP stack. When network is h3-l4proxy, traffic bypasses that stack, so ip-stack.mode cannot provide the same comparison. Do not change network just to follow this guide.

Without this build support, the pinned source returns gVisor IP stack requires the with_gvisor build tag. Undo the test if this occurs. Repeated reloads will not add build support. Older versions or other branches may not recognize the field or may ignore it; a successful configuration check alone does not prove it is used.

Some documentation languages may retain an earlier explanation of auto, so this guide checks its meaning against a pinned implementation with an explicit version. Configuration support in v1.19.32 does not prove that the reported issue affects that stable release. Do not install an Alpha core blindly for this comparison.

Change ip-stack only on the affected MASQUE node

The setting belongs inside an existing type: masque outbound node, with ip-stack at the same level as type and server. This differs from the TUN inbound stack. Setting tun.stack to gvisor does not perform this outbound comparison.

The snippet below is only the part to merge into the affected node, not a complete configuration. If ip-stack already exists, change only its mode and preserve its other fields. If it was absent, record that so you can restore the exact original state.

Partial YAML for the affected MASQUE node; not a root-level or TUN configuration
ip-stack:
  mode: gvisor

Keep the original configuration and compare one node

  1. Find the node carrying the failed request

    Use connection records to confirm that the request uses the affected MASQUE node; do not infer this from the selected policy group name alone. Save the original subscription or local configuration, the node’s original values, and an already working fallback node.

  2. Change mode in a persistent copy

    In a local configuration copy you maintain, or a persistent override explicitly supported by the client, change only this node’s ip-stack.mode to gvisor. Remote subscription updates may overwrite a cached copy. If you cannot save it reliably, contact the configuration maintainer first instead of editing temporary files.

  3. Check the configuration and confirm that the app loaded it

    Use the running core’s configuration check. When running Mihomo directly, use -t and -f with the actual paths. After saving, inspect the affected node in the final configuration, the running core, and startup logs. Restore the original copy if there is a configuration or build error.

  4. Compare using a new request

    Start a new request for the same target file while keeping the node, network, and other settings unchanged. An already established TCP connection is not a new request using the changed IP stack. Record the result before deciding whether to keep the setting.

How can you tell whether the comparison helped?

Use a test file you are authorized to access that is not an installer, and set limits on test duration and traffic in advance. Record the original behavior, then retry under the same conditions. You do not need the huge file used in the report, or ever larger downloads just because a short test does not reproduce it.

If it stalls again, preserve the records and start a new short request. An old download that stops growing while a new request works is closer to the reported pattern. A speed-test number, one loaded page, or an absence of error logs cannot independently prove that long connections have recovered.

Keep these five verification results

  • The actual core version, Use tags, and affected node configuration refer to the same running core.
  • Only the intended ip-stack.mode changed in the final configuration; the original value and independent backup remain available.
  • A new request for the same target file continues receiving data. Record whether it reached a time limit, was cancelled, or completed naturally; these are different outcomes.
  • The new-connection comparison during the stall, the actual outbound, and brief logs are recorded. General connection loss or policy group switching has not been mistaken for a single-connection fault.
  • After reloading the configuration and selecting the node again, the setting remains saved and actual requests behave consistently with the previous test. A short test supports a conclusion only for its observation period.

How do you roll back and report a failure?

If the configuration fails, build support is missing, or connectivity worsens, restore the node’s original ip-stack contents. If the setting was absent, remove only what this test added. Reload and verify the original configuration, then return to a previously working fallback node or configuration. Reinstallation or clearing all data is unnecessary for this rollback.

Even if the gvisor comparison improves the current request, it establishes only a temporary result in this environment, not a project fix. If both settings fail or all new connections also fail, preserve the evidence and investigate the actual error instead of forcing it into the same IP stack diagnosis.

Provide the actual core version and build tags, platform, actual mode, a minimal redacted configuration, the time and received data when the request stopped, and results for new connections on the same tunnel. Remove private-key, account details, subscription Token values, and other secrets. Complete credentials or continued large transfers are unnecessary for reporting.

This guide reviewed official documentation and pinned source code. It did not reproduce the issue on a real router or independently verify the reporter’s performance data. Confirmation of a cause, a released fix, or changed defaults must come from new maintainer conclusions and explicit version records.

References