Common questions and problems

English | 简体中文

Note

This page covers m-ui-specific checks first. For general Linux, firewall, DNS, and SSH problems, use your distribution's documentation as well.

1. The panel does not open after installation

Check the service and settings:

m-ui status
m-ui settings
m-ui logs

Confirm that the firewall allows the configured panel port and that the URL contains the generated URI path. If the panel uses HTTPS, use https:// and verify the certificate paths.

If the panel is listening only on loopback, set Panel Settings → General → Listen IP to the intended interface and restart m-ui.

2. I lost the administrator password

On the server, run:

m-ui reset-credentials

Enter a new username/password or leave fields blank to generate them. Save the printed credentials.

3. I changed the panel path and was locked out

The old URL stops working after the path is changed. Read the current setting with m-ui settings. The printed path includes the leading and trailing slash.

4. The browser shows a certificate warning

Check that the certificate covers the hostname and that the certificate/key paths are both configured. For an ACME-managed certificate, use m-ui ssl list. Apply an existing pair with m-ui ssl set, then restart m-ui. If TLS terminates at Nginx or Caddy, configure the proxy certificate there and forward X-Forwarded-Proto.

5. My provider blocks port 80

Use Cloudflare DNS validation instead of HTTP-01:

m-ui ssl cloudflare

The domain must use Cloudflare DNS. Prefer a scoped API Token with Zone:DNS:Edit and Zone:Zone:Read, limited to the target zone.

6. Mihomo will not start

Click Test Current Config, inspect the raw YAML, and read m-ui logs. Common causes are:

• duplicate inbound names
• a port used by the panel, API, subscription service, or another inbound
• an outbound group referring to a missing proxy
• a WARP rule without a valid WARP WireGuard outbound
• invalid TLS/Reality key material
• a core path that is not executable

7. I changed an inbound but Mihomo still behaves as before

Saving writes panel state and regenerates config.yaml; it does not reload a running core. Click Restart Mihomo after saving.

8. The YAML editor rejects my outbound

Ensure the YAML contains a name and valid Mihomo type. The editor accepts a single node, a sequence, or proxies/proxy-groups documents. Switching between Form and YAML does not apply incomplete drafts; validation occurs when Apply/Save is clicked.

Sharing-link conversion is local and does not fetch remote subscription URLs. Check that the link scheme is supported by the converter.

9. WARP registration fails

WARP registration uses Cloudflare's consumer API. Check DNS, outbound Internet access, and the panel log. If the account exists but the outbound is missing, open WARP and click Add Outbound, then Save and Restart Mihomo.

10. A subscription URL returns 404

Check all of the following:

• the URL uses the current Subscription Path
• the Username token has not been regenerated
• the required client conversion is enabled
• the client still exists in at least one enabled inbound
• a dedicated subscription port is reachable

The normal browser page has no client suffix. Add /clash only for Mihomo/Clash YAML.

11. A dedicated subscription port does not work

The port must differ from the panel, API, mixed, and inbound ports. Open it in the firewall and reverse proxy. The subscription listener serves subscriptions only; panel login and Multi-control remain on the panel port.

12. Multi-control pairing fails

Verify:

• both panels have local node addresses configured
• the target endpoint contains only scheme, host/IP, and panel port
• the pairing token is 16–32 lowercase alphanumeric characters containing letters and digits
• cloud and host firewalls allow panel-to-panel TCP access
• HTTPS certificates match the peer hostname
• the reverse proxy forwards /_m-ui/peer/v1
• both server clocks are synchronized

The hidden panel URI path is not part of the peer endpoint. The dedicated subscription port cannot be used for pairing.

13. A peer is offline

Inspect its error and last-seen fields. Offline peers are retried automatically, but m-ui cannot bypass NAT or provider firewalls. The advertised local address must be reachable from the other server, not merely from your browser.

14. Sync Inbound completed but traffic is not flowing

success means the target saved the inbound and generated YAML. Restart Mihomo on the target. Check target-side port conflicts, listen IPs, certificates, outbound names, and firewall rules.

15. Cross-panel subscriptions show stale nodes

Cross-panel data is cached by design. Run Pull all inbound information again. If a peer is unavailable, its last successful cache is retained. Use Clear remote cache only when you want to remove all non-local cached sources.

16. Reverse-proxy panel works but peers do not

Forward these paths to the panel listener, not the subscription listener:

/_m-ui/peer/v1
/_m-ui/peer/inbound/v1

Preserve Host and forwarded headers and do not prepend the hidden panel path.

17. The panel uses too much disk

Inspect data and journal usage:

du -sh /usr/local/m-ui/data
journalctl --disk-usage

Remove obsolete backups and use m-ui clear-logs for service logs. Do not delete state.json or config.yaml while the service is running.

18. GitHub download fails during install

The installer uses GitHub Releases and raw GitHub files. Check DNS, IPv4/IPv6 reachability, proxies, and timeouts. You can supply a local binary with MUI_BINARY_PATH; Mihomo still needs a compatible core unless --skip-mihomo is used.

19. The management script was updated but the binary was not

m-ui update-menu refreshes only the shell management script. Use m-ui update to download a new m-ui binary.

20. How do I report a bug?

Include the m-ui version, Mihomo version, operating system/architecture, sanitized error, and smallest reproducible configuration. Remove passwords, UUIDs, subscription/pairing tokens, certificates, private keys, public IPs, and domains before posting.