Troubleshooting

Work through Tunna setup, connection, routing, subscription, asset, and logging problems.

June 2, 2026 6462 words 29 min

Use this page as a run book. Start with one known node and simple routing, make one clean attempt, then read the newest facts Tunna gives you. Most problems come from the selected node, the route plan, the Apple Network Extension, provider updates, assets, imports, or logs that are too quiet.

Start from the symptom, not every setting

Pick the branch that matches what you can reproduce once, then collect the newest Tunna evidence before changing more fields.

Use these cards as a map of the visible labels in this view. Each card names one field, control, or status item and explains what it is for before you change it or rely on it.

Visible choices

These are controls, states, or measurements in the view. Read them as reference, not as feature claims.

Tunnel will not stay running

Check manual Power, the Apple Network Extension state, one selected node, and the newest log rows.

Traffic uses the wrong route

Check rule order, paused state, Default Route, Proxy versus Freedom, and whether the condition can match that traffic.

Subscription or asset is stale

Check fetch status, provider metadata, update timing, asset processing state, and whether Resources is waiting for review.

Logs or stats look quiet

Make one clean reproduction, then compare Log, Debug, Observability, latency, packet loss, and data counters.

Need community support?

Post one focused report after you reproduce the problem once. Include the Tunna version, whether the node is local or from a subscription, the selected protocol, the expected route, and the newest log entries after the attempt.

Community Support

Redact UUIDs, passwords, Reality keys, node links, and subscription URLs before sharing.

First pass for any connection problem

Select one known node

Use a local node or a subscription node with recent latency. Do not switch between several nodes during the same test.
Use simple routing

Use Proxy as the Default Route and pause custom rules while testing. This separates node problems from rule problems.
Start manually

Set automatic startup aside until the basic connection works. Tap Power once and wait for the attempt to finish.
Clear and reproduce

Clear logs, enable Debug only if the first attempt is too quiet, reproduce once, then read the newest entries first.
Restore one piece at a time

After the node works, turn rules, assets, automatic startup, and advanced settings back on slowly.

Common symptoms

Symptom	Check first	What to try
No Outbounds Available	Outbound and Subscriptions	Add a local node, scan or paste a node link, or update the subscription profile.
Failed to Connect	Protocol, transport, and security	Compare the node with the provider profile. Server Name and Address are often different.
Save is disabled	Manual node fields	Fill the required address, port, and credential values for the selected protocol.
Tunnel starts then stops	Newest log entries	Clear logs, enable Debug for one attempt, start manually, then read the newest entries for the first startup error or configuration conflict.
Tunnel will not start	Node and route configuration	Use Debug for one reproduction. A conflict usually means the selected node, transport, security, route, DNS, or tunnel setting does not describe one coherent setup.
Power looks stuck	Network Extension state	If the visible Power control accepts a long-press while still connecting or disconnecting, use it to reinitialize the Network Extension. If Power is off, failed, quiet, or cannot be long-pressed, use the Reset screen instead.
Traffic is not proxied	Routing	Confirm Default Route is Proxy, or add a Proxy rule above broader direct rules.
Connected, but pages still do not load	Traffic flow	Test one known node with Default Route set to Proxy, then use Access or DNS logging for one attempt if the route or name lookup is unclear.
Local devices disappear	Private Subnets	Check whether private subnet traffic should enter the VPN tunnel. Test one router, printer, NAS, or local-service address.
Only DNS, TLS, HTTP, QUIC, or app protocol rules fail	Sniffing and Domain Strategy	Use a simple domain rule first, then enable only the recognition features the rule actually needs.
Sites change after enabling IPv6	IPv6 route plan	Disable IPv6 and repeat the same site test. Re-enable it only when the network, provider, rules, and assets all support the path.
A rule does not match	Rule order and conditions	Move the rule higher, unpause it, check domain type, and use Sniffing for application protocol rules.
Asset rule finds no records	Installed assets	Add predefined assets or update the remote asset, wait for processing to finish, then search the Asset tab again.
Subscription is failed, expired, or outdated	Status footer, network, and source URL	Check connectivity, provider URL, user agent, provider expiry, and whether the fetched profile still contains usable node links.
Import is disabled in Resources	Selection and pending fetches	Select at least one item, then wait for subscription nodes or rule assets to finish fetching. Deselect failed or unwanted items before importing.
No Logs Found	Log controls	Raise severity, enable Access or DNS only for the test, reproduce the issue, then lower log detail.
Battery, data, or storage usage feels high	Log and probes	Turn off Debug, Access, and DNS logging after the test. Lengthen probe intervals or lower concurrency when you are not actively comparing nodes.
A provider update changed routing	Subscription cleanup	Review rules that targeted subscription nodes after a provider refresh removed or renamed nodes.

Frequently Asked Questions

Use this as the compressed version of the manual. Each answer points to the screen or setting family that owns the work.

Setup

Starting and importing

What do I need before Tunna can connect?

You need a local node, subscription URL, QR code, provider link, Tunna share link, or manual server details; the first Power tap then installs the Apple Network Extension entry.

What is Resources for?

Resources is the review screen for imported nodes, rules, subscriptions, duplicate warnings, and required fetches before anything is saved.

When should I use a local node instead of a subscription?

Use a local node for one server you maintain; use a subscription when a provider manages a changing node list, quota, expiry, profile, or support link.

Which links are private?

Treat node links, QR codes, subscription URLs, Tunna share links, UUIDs, passwords, and Reality keys like credentials.

Outbound

Nodes and providers

Which protocol should I choose?

Choose the protocol named by the provider: VLESS, VMess, Trojan, or Shadowsocks. Do not translate one protocol into another.

Where do address, port, server name, and path belong?

Address and Port point to the server listener; transport path, TLS server name, Reality keys, and fingerprints live in their matching transport or security fields.

What do latency dots and values mean?

They summarize recent reachability and RTT. Tap them to open Stats, and let checks warm up before trusting ZAP, Top 10, or sorting.

Why does a subscription fail or look stale?

Check the Source URL, network, User Agent, provider expiry, fetch status, and whether the fetched profile still contains supported node links.

Rules

Routing decisions

What does Default Route do?

Default Route handles traffic that no rule catches. Use Proxy for broad proxying, Freedom for direct traffic, or Blackhole for blocking.

Why does a rule not match?

Move the rule above broader rules, unpause it, confirm the domain type or IP range, and check Sniffing when the rule depends on HTTP, TLS, or BT application protocol recognition.

How should rule edit tabs be read?

Start with the outcome, then add only the needed conditions: domains, IP ranges, ports, network type, protocol, app protocol, or assets.

What can wake On-Demand?

Use unpaused Proxy rules with ordinary domain entries or usable GeoSite records; Default Route, IP-only, GeoIP-only, ports, and paused rules do not wake the tunnel.

Assets

Assets and matching

What is the difference between GeoSite and GeoIP?

GeoSite groups domains; GeoIP groups IP ranges. Use GeoSite for host names and GeoIP only when IP-based routing is intentional.

Why does an asset-backed rule find no records?

Install predefined GeoSite or GeoIP assets, update the trusted remote asset, and wait for fetching and processing to finish before searching the Asset tab or judging the rule.

When should I change Domain Strategy?

Keep AsIs for ordinary domain routing; use IPIfNonMatch or IPOnDemand only when IP rules must see DNS results and you accept extra DNS work.

What does Sniffing add?

Sniffing can recognize destination names and application protocols from supported traffic; it helps matching but does not decide Proxy or Direct by itself.

Tunnel

Tunnel behavior

What should Connect be set to?

Use Never while testing, Always On after the node is reliable, and On-Demand only when routing rules are ready to wake the tunnel.

What does Disconnect On Sleep do?

It asks Apple to stop the VPN tunnel when the device sleeps. Use it for battery-aware operation, not to repair a bad node.

How do Trusted Networks work?

Trusted Networks define Wi-Fi or cellular entries where Tunna should avoid or stop the tunnel; Save commits the child sheet, Cancel leaves it unchanged.

Should I enable IPv6 or network routing toggles?

Only enable traffic categories and IPv6 paths your device, network, provider, and rules can handle; entering the VPN does not automatically mean traffic is proxied.

Observability

Logs, checks, and stats

How often should probes run?

Use short intervals only while choosing nodes; longer intervals save battery and data once latency and status are stable.

What do node colors mean?

Colors summarize recent probe results: fast, slow, failing, or unknown. Unknown usually means the node has not been checked recently.

When should Debug logging be enabled?

Enable Debug for one clean reproduction or when support asks, then lower severity and turn off Access or DNS logging because it costs battery, storage, and data.

What should I read first in logs?

Read the newest entry after the failed start or traffic test. The first concrete error usually beats older noise.

Recovery

Reset and support

When should I reset the Network Extension?

Use a Power long-press only while connecting or disconnecting is stuck; otherwise use Reset Network Extension from the Reset page.

When should I reset user data?

Reset only the broken area, such as Routing, Outbound, Assets, Subscriptions, Log, Tunnel, or Observability. Reset All is the last resort.

What should I send support?

Send Tunna version, node source, protocol, transport, security, expected route, network type, newest logs, and recent imports, updates, or resets.

What should I redact?

Hide node passwords, UUIDs, Reality keys, subscription URLs, server links, and copied Debug JSON that contains credentials.

Use Reset carefully

Reset Network Extension rebuilds the system VPN entry. Reset User Data can remove selected app settings and cannot be undone. Prefer targeted reset options over Reset All.

Power changes meaning with tunnel state

Use tap and long-press actions for the state Tunna is actually in. The long-press is a convenience action when the tunnel is healthy, and a recovery action only when the tunnel is stuck.

Use these cards as a map of the visible labels in this view. Each card names one field, control, or status item and explains what it is for before you change it or rely on it.

Visible choices

These are controls, states, or measurements in the view. Read them as reference, not as feature claims.

First tap

When no system VPN entry exists yet, the first Power tap installs Tunna's Apple Network Extension entry. Approve the system VPN prompt before expecting traffic to pass.

Connected with Always On

A long-press disables Always On and stops the tunnel. It does not disable On-Demand. If On-Demand causes restart loops, set Connect back to Never in Tunnel settings while diagnosing.

Disconnected on a trusted network

A long-press can mark the current trusted network untrusted only when Power is disconnected. If the tunnel is still connected on a trusted network, wait for automatic disconnect, set the relevant auto-connect mode back to Never while diagnosing, or remove that network from Trusted Networks.

Connecting or disconnecting

If Power stays on connecting or disconnecting and the visible control accepts a long-press, long-press Power to reinitialize the Network Extension. If Power is off, failed, quiet, or cannot be long-pressed, use the Reset screen.

Reset User Data options in plain words

Reset only the part that is broken. Reset All returns Tunna's app data to a new-install shape and should be the last resort.

Use these cards as a map of the visible labels in this view. Each card names one field, control, or status item and explains what it is for before you change it or rely on it.

Traffic plan

These options affect what Tunna uses to connect and how traffic is sorted.

Routing

Removes your route plan and returns rule behavior to the default setup.

Outbound

Removes saved nodes and returns the built-in direct, block, and DNS entries. Rules that pointed at removed nodes can fall back to the current Proxy node, so pause or reassign those rules before reconnecting. Reset Routing too if you want the route plan removed.

Subscriptions

Removes provider profiles and their subscription nodes. Rules that pointed at those nodes can fall back to the current Proxy node, so pause or reassign them before reconnecting. Reset Routing too if you want the route plan removed.

Assets

Removes GeoSite and GeoIP records. Rules that only depended on those records are paused so they do not become broad empty rules.

Tunnel behavior

These options return connection recognition and tunnel defaults to their original values.

Tunnel

Resets Connect and Disconnect choices, trusted networks, network routing controls, and IPv6 behavior.

Sniffing

Resets destination recognition, excluded domains, metadata-only behavior, and routing-only behavior.

Inbound

Returns the local entry point Tunna uses inside the tunnel to its default shape.

Policy

Returns timeout, buffer, and resource policy behavior to defaults.

Protocol

Returns multiplexing plus Freedom, Blackhole, and DNS defaults. Existing proxy nodes keep their server identity; eligible nodes receive the default multiplexing behavior.

Diagnosis records

These options affect what Tunna has remembered while checking or explaining behavior.

Log

Returns log detail choices to defaults.

Observability

Clears health-check history and usage/latency records, then returns check settings to defaults.

When the tunnel starts then stops or will not start

Use this when Power appears to start the tunnel but falls back to disconnected, or when the tunnel refuses to start. The goal is one fresh attempt and the first useful error.

Make the test quiet

Select one known node, keep routing simple, and turn off automatic startup while you investigate. If several features are changing at once, the log becomes harder to trust.
Enable Debug for one attempt

Open the Log screen, clear old entries, and raise severity to Debug. Turn on Access or DNS only if the problem is about traffic flow or name resolution.
Start manually

Return to the connection screen and tap Power once. Wait for Tunna to finish the attempt instead of changing nodes immediately.
Read the newest entries first

Look for the first error after the start attempt. If it points to a configuration conflict, compare the node protocol, transport, security, server name, route, DNS, and tunnel settings with the provider profile.
Lower logging again

After the test, lower severity and turn off extra Access or DNS logging unless support asked you to keep them on. Debug can burn battery, data, storage, and attention fast.

Reset the Apple Network Extension when the tunnel is stuck

Use this for a stale or confused system VPN entry. It does not fix a bad node profile; test the node and routing first.

Try the Power long-press when the control is stuck

When Power is still connecting or disconnecting after a start or stop attempt and the visible control accepts a long-press, long-press Power. Tunna removes and saves the Network Extension entry again.
Do not use long-press as a normal disconnected reset

When the tunnel is disconnected, failed, quiet, or shown by an older Power control that cannot be long-pressed while in progress, use the Reset screen for a deliberate Network Extension reset.
Use the Settings reset path

Open the Reset page, then choose Reset Network Extension. Confirm the reset. Tunna stops the tunnel, removes the system VPN entry, and saves a fresh one. If Reset Network Extension is disabled, no system VPN entry exists yet; tap Power once to create it, approve VPN permission if asked, then return to this reset if you still need it.
Start manually after the reset

Return to Outbound, select a known node, keep routing simple, and tap Power. If the system asks for VPN permission again, approve it.

Useful facts for support

Tunna app version from About.
Whether you are asking the Tunna community or using a provider support link from a subscription profile.
Whether the node is local or from a subscription.
Selected protocol, transport, and security names.
Default Route and the name of any rule you expected to match.
Whether the issue happens only on Wi-Fi, cellular, or a trusted network.
Newest log entries after reproducing the issue.
Whether a subscription update, asset update, rule edit, import, or reset happened just before the problem.
Whether the problem came from a pasted link, QR code, system share link, command link, or Siri shortcut.
Whether Debug showed Configuration Not Found, Configuration Parse Failed, or Configuration Load Failed.

Support screens in Misc

Use these only when ordinary checks in Outbound, Routing, Tunnel, Subscriptions, Assets, Observability, and Log do not explain the problem.

Use these cards as a map of the visible labels in this view. Each card names one field, control, or status item and explains what it is for before you change it or rely on it.

Visible choices

These are controls, states, or measurements in the view. Read them as reference, not as feature claims.

About

Use Application Version when reporting a problem. Community opens the Tunna community link.

Reset

The Danger Zone contains Reset Network Extension and Reset User Data. Tunna warns that selected app settings cannot be restored after the reset.

Debug

Debug shows the running configuration as expandable JSON. Long-press a row to copy that part of the JSON only when support asks for it.

Redact secrets before sharing

When sending screenshots or logs, hide node passwords, UUIDs, subscription URLs, Reality keys, and any link that could let someone else use your server.

Turn Debug back off

Use Debug for one clean reproduction or when support asks for it. Then lower severity again and turn off Access or DNS unless you still need them. Debug is noisy and expensive for battery, storage, and data.