Skip to main content
Use the exact error text to find the relevant section on this page. A dialog such as Startup failed: ... is usually only the outer message. The actual cause follows the colon or appears in the last core| entry in the startup log.

Export startup logs

Go to Settings -> About -> Export logs to generate a diagnostic ZIP.

mihomo configuration documentation

Check core fields, proxy protocols, and rule syntax.

Submit an issue

Include the app version, core version, runtime mode, and redacted logs.
Logs and configurations may contain subscription URLs, proxy passwords, UUIDs, tokens, domains, and IP addresses. Redact them before posting publicly, and do not upload a complete subscription file.

​
Start with these four steps

1

Record the exact error

Do not record only “Startup failed.” Copy the complete error, especially prefixes and indexes such as parse source yaml:, rules[n], and proxy [...] not found.
2

Temporarily disable overrides

Enable “Disable all overrides” in network settings and start again. If startup succeeds, the problem is in a YAML/JavaScript override or the visual routing configuration.
3

Distinguish the runtime mode

Test the configuration with VPN Service first. If only Root Tun / TPROXY fails, check Root authorization, SELinux, routing, and iptables.
4

Export logs

Immediately after reproducing the issue, go to Settings -> About -> Export logs. The ZIP contains local VPN records, Root startup records, and core.log.

​
Configuration and core errors

The errors below come from the current Rust configuration compiler, Android startup path, and mihomo core. Names and indexes vary with the configuration.
Common errors
The YAML syntax or field type is invalid. Common causes include mixed indentation, a missing space after a colon, Tab indentation, an unquoted string, or an object field written as a list.Resolve the issue in this order:
  1. Open the source configuration and enabled overrides in the app editor, then fix the reported line and column.
  2. Confirm that the top level is a YAML object, not an array or a single string.
  3. Disable all overrides and try again to determine whether the error comes from the subscription or an override.
The compiled top-level configuration is not an object. This commonly happens when a configuration contains only - item, or when a JavaScript override returns an array, string, or null.The top level of the YAML should look like this:
Valid top-level structure
JavaScript main(profile) must return an object or a Promise that resolves to an object.
Core error
Rule n is missing a type, match value, or target policy group. Use the complete rule in the error to check the number and order of commas.
Rule examples
Core error
A rule target, dialer-proxy, or tunnel references a proxy or policy group that does not exist. Names are case-sensitive and must exactly match proxies[].name or proxy-groups[].name.If an override adds the name, check the order in which overrides are applied. When deleting a policy group, also update every rule that references it.
Core error
A RULE-SET, DNS field, or Tun field references a rule-providers name that does not exist.
​
object
required
The provider name must exactly match the rule reference.
​
domain | ipcidr | classical
required
The behavior must match the format of the provider file.
Core error
The policy group is missing name or type, uses a type unsupported by the current core, or has no proxy source.
​
string
required
Policy group name. It cannot be empty.
​
string
required
For example, select, url-test, fallback, or load-balance.
​
string[]
required
Provide at least one direct proxy list or proxy provider list.
Common errors
The configuration is encrypted with Age, but no matching identity was provided during import or the secret-key format is unsupported.
  • Use a private key/identity, not a recipient public key.
  • Put each key on a separate line and remove leading or trailing spaces.
  • Import the configuration again and provide the key; renaming an existing configuration does not add a missing key.
  • Never post the private key in an issue, group chat, or screenshot.
The subscription or external provider returned an error status. YumeBox does not treat an HTTP error page as a valid subscription configuration.
​
http | https
required
Confirm that the address has not expired or been truncated and is reachable from the current network.
​
object
Some providers require authentication headers. Check the header names and values in the configuration.
401/403 usually indicates a token, User-Agent, or access-policy problem. 404 usually indicates an invalid path. 5xx indicates a temporary server-side failure.
YumeBox prefetches proxy-providers and rule-providers during import. The core also fetches missing resources after it starts. If a download fails, check the following fields:
​
string
required
The URL must be a reachable HTTP(S) address.
​
http | file | inline
A provider that needs a network download normally uses http.
​
string
Use a relative path. Absolute paths or paths that escape the profile directory are rewritten or rejected.
Also confirm that the provider returns mihomo provider YAML/MRS rather than a web page, login page, or ordinary subscription link.
The compiled provider path escaped the current configuration’s private providers/rules or providers/proxies directory. This check prevents different subscriptions from overwriting each other’s resources.Remove absolute paths, ../, legacy ./ruleset/ paths, and paths containing /clash/ from overrides. Let YumeBox generate an isolated path from the provider name.
The only supported override extensions are .yaml, .yml, and .js.
Common errors
Disable the most recently added override and try again. A JavaScript override must define main(profile) and return an object; an asynchronous function must resolve within a finite time. See the YAML API and JavaScript API for syntax details.
Core startup error
This is the outer error for the core parsing stage. The actual cause appears later on the same line and commonly involves invalid rule references, policy groups, DNS, Tun, or proxy protocol fields. Search this page for the remaining error text.

​
VPN, Root, and startup errors

Android did not return a usable VPN interface.
  • Accept the system VPN permission dialog.
  • Stop other VPNs, work-profile VPNs, or always-on VPNs.
  • Revoke YumeBox’s VPN permission in system settings, then grant it again.
  • If the device vendor restricts background startup, allow YumeBox to run in the background.
Root startup error
The Tun and TPROXY runtime modes require a working su. Confirm that the Root manager has authorized the currently installed package and that permission is not set to “Only once.” After an update or signing-key change, the Root manager may treat the app as a new client and require authorization again.
The system rejected an attempt by the core to create a Tun interface, write routes, run iptables, or execute a native binary.
  • Under VPN Service: check system VPN permission and vendor background restrictions.
  • Under Root Tun: check su authorization, SELinux policy, and /dev/net/tun.
  • Under TPROXY: confirm that the kernel supports TPROXY and the system has the relevant iptables modules.
  • Only with a self-built APK: confirm that all four native files for the target ABI were packaged.
The Root process may still exist, but the controller Unix socket is not ready or the core exited after startup. Export logs and inspect the last line of core.log. Common causes are still a configuration parsing failure, configuration-pipe read failure, or socket creation failure.Stop the proxy, make sure no Root daemon remains, and start again. Do not determine core availability only from whether a notification is present.
The startup coordinator did not observe the Running state within the expected time. The core may be blocked, the Root daemon may not be responding, the controller may be unreachable, or the system may have frozen the background service.Stop the service, force-stop the app, reopen it, and start with VPN Service. If it still fails, export logs immediately. Do not tap the start button repeatedly in quick succession, because that makes stale state harder to diagnose.

​
Common symptoms

Start the proxy first, then open External resources and confirm that the proxy provider exists.
  • Inline proxies belong in top-level proxies.
  • External proxies belong in proxy-providers and must be referenced through a policy group’s use field.
  • Provider names are case-sensitive.
  • If the provider download failed, check the URL, headers, file format, and current network.
External provider proxies come from /providers/proxies, while ordinary proxies come from /proxies. Confirm that the core is running and the provider loaded successfully, then refresh the Proxies page.If only a new protocol is shown as Unknown, record the type returned by /providers/proxies or export logs, then submit an issue with the YumeBox and core versions. Do not include proxy credentials.
1

Switch to DIRECT to verify Tun

If DIRECT also cannot access the network, check VPN/Tun, DNS interception, IPv6, and access control first.
2

Check DNS

Temporarily use ordinary DNS servers from the configuration and disable suspicious fake-ip filters, rule sets, and overrides.
3

Check rule targets

Confirm that the final MATCH points to an existing policy group containing usable proxies.
4

Check Geo data

The first startup of an external APK downloads Geo resources. Use a builtin APK if the network is restricted.
An external APK does not contain Geo data. It is smaller but depends on the network during first use. A builtin APK contains GeoIP, GeoSite, ASN, and BundleMRS data. It is larger but does not require an initial download. Both use the same app features and core code.
Include at least the following information:
​
string
required
The version and installation source shown on the About page.
​
branch + commit
required
The mihomo branch and short hash shown on the About page.
​
VPN Service | Tun | TPROXY
required
Whether the same configuration starts in another mode.
​
string
required
Include the complete prefix, index, and final cause.
​
ZIP
required
Export them from the About page and remove credentials and private data before posting publicly.

Build from source

Follow the complete Android SDK, NDK, Go, Rust, native, and APK build process.
Last modified on July 24, 2026