> ## Documentation Index
> Fetch the complete documentation index at: https://yumebox.gal.tf/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

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.

<Columns cols={3}>
  <Card title="Export startup logs" icon="file-archive">
    Go to Settings -> About -> Export logs to generate a diagnostic ZIP.
  </Card>

  <Card title="mihomo configuration documentation" icon="file-code" href="https://wiki.metacubex.one/config/">
    Check core fields, proxy protocols, and rule syntax.
  </Card>

  <Card title="Submit an issue" icon="github" href="https://github.com/YumeYucca/YumeBox/issues/new/choose">
    Include the app version, core version, runtime mode, and redacted logs.
  </Card>
</Columns>

<Tip>
  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.
</Tip>

## Start with these four steps

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Distinguish the runtime mode">
    Test the configuration with `VPN Service` first. If only Root `Tun` / `TPROXY` fails, check Root authorization, SELinux, routing, and iptables.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

## 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.

<AccordionGroup>
  <Accordion title="parse source yaml / yaml: unmarshal errors" icon="braces">
    ```text Common errors theme={null}
    parse source yaml: ...
    yaml: unmarshal 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.
  </Accordion>

  <Accordion title="compiled root config must be an object" icon="box">
    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:

    ```yaml Valid top-level structure theme={null}
    mixed-port: 7890
    proxies: []
    proxy-groups: []
    rules:
      - MATCH,DIRECT
    ```

    JavaScript `main(profile)` must return an object or a Promise that resolves to an object.
  </Accordion>

  <Accordion title="rules[n] ... format invalid" icon="list-x">
    ```text Core error theme={null}
    rules[12] [...] error: format invalid
    ```

    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.

    ```yaml Rule examples theme={null}
    rules:
      - DOMAIN-SUFFIX,example.com,PROXY
      - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
      - MATCH,PROXY
    ```
  </Accordion>

  <Accordion title="proxy [name] not found" icon="route-off">
    ```text Core error theme={null}
    rules[8] [...] error: proxy [PROXY] not found
    proxy [node-a] dialer-proxy [relay] not found
    tunnel proxy PROXY not found
    ```

    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.
  </Accordion>

  <Accordion title="rule set [name] not found" icon="file-question">
    ```text Core error theme={null}
    rules[3] [...] error: rule set [private] not found
    dns.fake-ip-filter[0] [...] error: rule-set 'private' not found
    ```

    A `RULE-SET`, DNS field, or Tun field references a `rule-providers` name that does not exist.

    <ParamField body="rule-providers.<name>" type="object" required>
      The provider name must exactly match the rule reference.
    </ParamField>

    <ParamField body="rule-providers.<name>.behavior" type="domain | ipcidr | classical" required>
      The behavior must match the format of the provider file.
    </ParamField>
  </Accordion>

  <Accordion title="Policy group format error / unsupported type / use or proxies missing" icon="network">
    ```text Core error theme={null}
    format error
    unsupported type
    group-name: `use` or `proxies` missing
    duplicate provider name
    ```

    The policy group is missing `name` or `type`, uses a type unsupported by the current core, or has no proxy source.

    <ParamField body="proxy-groups[].name" type="string" required>
      Policy group name. It cannot be empty.
    </ParamField>

    <ParamField body="proxy-groups[].type" type="string" required>
      For example, `select`, `url-test`, `fallback`, or `load-balance`.
    </ParamField>

    <ParamField body="proxy-groups[].proxies / use" type="string[]" required>
      Provide at least one direct proxy list or proxy provider list.
    </ParamField>
  </Accordion>

  <Accordion title="Age decryption failed" icon="key-round">
    ```text Common errors theme={null}
    decrypt config error: ...
    decrypt age profile: ...
    no supported age secret keys found
    parse age secret key at line ...
    This config is encrypted with age. Please provide the age secret key ...
    ```

    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.
  </Accordion>

  <Accordion title="HTTP 401 / 403 / 404 / 5xx" icon="cloud-alert">
    The subscription or external provider returned an error status. YumeBox does not treat an HTTP error page as a valid subscription configuration.

    <ParamField body="url" type="http | https" required>
      Confirm that the address has not expired or been truncated and is reachable from the current network.
    </ParamField>

    <ParamField body="header" type="object">
      Some providers require authentication headers. Check the header names and values in the configuration.
    </ParamField>

    `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.
  </Accordion>

  <Accordion title="Provider download failed / external proxies are empty" icon="cloud-off">
    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:

    <ParamField body="proxy-providers.<name>.url" type="string" required>
      The URL must be a reachable HTTP(S) address.
    </ParamField>

    <ParamField body="proxy-providers.<name>.type" type="http | file | inline">
      A provider that needs a network download normally uses `http`.
    </ParamField>

    <ParamField body="proxy-providers.<name>.path" type="string">
      Use a relative path. Absolute paths or paths that escape the profile directory are rewritten or rejected.
    </ParamField>

    Also confirm that the provider returns mihomo provider YAML/MRS rather than a web page, login page, or ordinary subscription link.
  </Accordion>

  <Accordion title="Compiled provider path escaped profile scope" icon="shield-alert">
    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.
  </Accordion>

  <Accordion title="unsupported override extension / override execution failed" icon="file-warning">
    The only supported override extensions are `.yaml`, `.yml`, and `.js`.

    ```text Common errors theme={null}
    unsupported override extension: ...
    parse yaml override ...
    Script execution failed: ...
    JS override result must be an object
    JS override rejected: ...
    async main(profile) did not settle
    ```

    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](/en/override/yaml) and [JavaScript API](/en/override/js-override) for syntax details.
  </Accordion>

  <Accordion title="mihomo: parse compiled config" icon="terminal">
    ```text Core startup error theme={null}
    mihomo: parse compiled config: ...
    Parse config 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.
  </Accordion>
</AccordionGroup>

## VPN, Root, and startup errors

<AccordionGroup>
  <Accordion title="VPN permission denied / Establish VPN rejected by system" icon="shield-x">
    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.
  </Accordion>

  <Accordion title="root core launch failed" icon="badge-alert">
    ```text Root startup error theme={null}
    root core launch failed (success=false ...)
    Tun / TPROXY requires usable Root permission for YumeBox
    ```

    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.
  </Accordion>

  <Accordion title="permission denied / operation not permitted" icon="lock-keyhole">
    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.
  </Accordion>

  <Accordion title="root core controller unavailable" icon="unplug">
    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.
  </Accordion>

  <Accordion title="runtime activation timed out / startup remains in progress" icon="timer-off">
    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.
  </Accordion>
</AccordionGroup>

## Common symptoms

<AccordionGroup>
  <Accordion title="The configuration imported successfully, but the policy group has no proxies" icon="list-tree">
    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.
  </Accordion>

  <Accordion title="The proxy protocol is shown as Unknown" icon="circle-help">
    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.
  </Accordion>

  <Accordion title="Connected, but the network is unavailable" icon="wifi-off">
    <Steps>
      <Step title="Switch to DIRECT to verify Tun">
        If DIRECT also cannot access the network, check VPN/Tun, DNS interception, IPv6, and access control first.
      </Step>

      <Step title="Check DNS">
        Temporarily use ordinary DNS servers from the configuration and disable suspicious fake-ip filters, rule sets, and overrides.
      </Step>

      <Step title="Check rule targets">
        Confirm that the final `MATCH` points to an existing policy group containing usable proxies.
      </Step>

      <Step title="Check Geo data">
        The first startup of an external APK downloads Geo resources. Use a builtin APK if the network is restricted.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="What is the difference between external and builtin Geo?" icon="database">
    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.
  </Accordion>

  <Accordion title="How do I submit an actionable issue report?" icon="message-square-code">
    Include at least the following information:

    <ResponseField name="YumeBox version" type="string" required>
      The version and installation source shown on the About page.
    </ResponseField>

    <ResponseField name="Core version" type="branch + commit" required>
      The mihomo branch and short hash shown on the About page.
    </ResponseField>

    <ResponseField name="Runtime mode" type="VPN Service | Tun | TPROXY" required>
      Whether the same configuration starts in another mode.
    </ResponseField>

    <ResponseField name="Exact error" type="string" required>
      Include the complete prefix, index, and final cause.
    </ResponseField>

    <ResponseField name="Redacted logs" type="ZIP" required>
      Export them from the About page and remove credentials and private data before posting publicly.
    </ResponseField>
  </Accordion>
</AccordionGroup>

<Card title="Build from source" icon="hammer" href="/en/guide/build" horizontal>
  Follow the complete Android SDK, NDK, Go, Rust, native, and APK build process.
</Card>