Support

Troubleshooting

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

Updated 2026-06-02

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.

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

When a subscription will not update

Confirm the Source remote URL is present and still opens from the current network.
Check the status footer for the exact failure text.
Try the provider-required User Agent if the default Tunna identity is rejected.
If the provider profile is expired, renew it with the provider before changing node fields.
If the fetch completes but no nodes appear, the provider response may not contain supported node links.
After a successful refresh, review rules that targeted subscription nodes the provider removed.

When assets or asset rules misbehave

If the Asset tab has no records, add the predefined GeoSite and GeoIP assets or update the remote asset source you trust.
Wait for fetching and processing to finish before judging search results. Asset search is limited while Tunna is still processing records.
If a rule stopped matching after an asset update, open the rule and confirm its asset chips still exist.
If an asset was deleted, rules that depended only on removed records are paused so they do not become broad empty rules.
Use ordinary domain rules for a quick test when an asset source is still downloading, failed, or not trusted.

When rules or imports do not work

For a rule that does not match, move it above broader rules, unpause it, and confirm its outcome is Proxy, Freedom, Blackhole, or the intended specific node.
For domain rules, check whether Base, Full, Plain, or RegEx matches the destination you meant.
For application protocol rules, check Sniffing. Tunna must recognize HTTP, TLS, or BT before those rule conditions can match.
For imports, wait until Resources finishes fetching subscription nodes and rule assets. Import stays unavailable while required resources are pending.
Review duplicate warnings before importing. Use Replace Rules only when you mean to pause existing matching rules and insert the selected imported rules at the top.
If a pasted link is ignored, confirm it is a Tunna share link, a supported node link, a subscription URL, or pasted rule data.

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.

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.

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 contacting Tunna support at [email protected] or 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.

About

Use Application Version when reporting a problem. Contact Support opens an email to Tunna support, and 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.