Updated 23 October 2026

Troubleshooting

Short answer: almost every problem is one of four things. The iPhone is still on the Mac's Wi‑Fi, the mesh VPN isn't connected on the iPhone, the iPhone's debugging port changed (use Scan port), or the license needs attention. The sections below match the exact messages Nuticast shows.

Quick checks

1. The iPhone is on a different Wi‑Fi from the Mac. Not cellular.
2. The same mesh VPN (Tailscale, ZeroTier, Netbird, or the one you use with Manual IP) is connected on both the Mac and the iPhone. On iOS, open the VPN app and check it says connected.
3. The iPhone was paired with Xcode once while it was next to the Mac, and Developer Mode is on.
4. The Mac is awake and online.

If Xcode can't see the phone even on the same Wi‑Fi, that's an Xcode pairing problem rather than a Nuticast one. Start with Xcode wireless debugging not working? A step-by-step checklist.

Bridge errors

When a bridge fails, the device shows Error with one of these messages.

"The device is still on this Mac's local network. Move it to a different Wi‑Fi before bridging." Nuticast refuses on purpose: bridging a phone that is still local would clash with Xcode's normal wireless debugging. Move the iPhone to another Wi‑Fi and start the bridge again. On the same Wi‑Fi you don't need Nuticast at all.

"The device isn't responding. Confirm Tailscale is connected on the iPhone." (or ZeroTier, Netbird) The Mac can't reach the iPhone over the mesh VPN. Open the VPN app on the iPhone and reconnect, check both devices are on the same mesh network, and check the iPhone is awake. iOS can drop a VPN after a while; the setup guides for Tailscale, ZeroTier and Netbird cover keeping it connected.

"The device's debugging port may have changed. Try Scan port." The iPhone's wireless debugging service no longer answers on the port Nuticast saved. Click Scan port on the device. Nuticast finds and saves the new port. A full scan can take a few minutes.

"Reached the device, but not on the wireless debugging port. Try Scan port." The saved port belongs to something else, often the VPN app's own service. Scan port fixes it.

"Couldn't reach the device. Confirm Tailscale is connected on the iPhone." No port on the iPhone answered at all. Same fix as "not responding": reconnect the mesh VPN on the iPhone.

"Wireless debugging isn't available over Tailscale. On the iPhone, check Settings → Developer → Wireless Debugging." The network path works, but the iPhone isn't offering wireless debugging on the VPN connection. Check that setting, and that the VPN allows incoming connections to the iPhone.

"Couldn't determine this Mac's network address." The Mac has no Wi‑Fi or Ethernet address right now. Reconnect the Mac to a network and try again.

"A required local port is busy. Try again, or restart Nuticast." Another process on the Mac holds a port the bridge needs. Retry; if it persists, quit and reopen Nuticast.

"The connection to the device was interrupted." The bridge was up and then dropped, usually because the iPhone lost Wi‑Fi or the VPN. Fix the connection and switch the bridge on again.

What the statuses mean

• Off: not bridging.
• Pairing…: checking that the phone is remote and finding its port.
• Bridge active: Xcode can see and debug the phone.
• Error: the message says why. A bridge in Error doesn't retry on its own: fix the cause, then switch it on again.

The bridge is active but Xcode doesn't show the iPhone

• Bridging from both the app and the command line. Use one or the other for a device. Opening the menu bar app clears bridges started with nuticast up, because it removes their Bonjour records at launch. If you bridge from the CLI or an AI agent, keep the app closed.
• A leftover registration. Switch the bridge off and on. Nuticast removes stale Bonjour records when it starts, so quitting and reopening the app also clears them.
• Xcode needs a moment. Give it a few seconds, then check xcrun devicectl list devices.

Adding a device

• "No mesh-VPN client detected." Install Tailscale, ZeroTier or Netbird on the Mac, or pick Manual IP and type the address your mesh VPN gave the iPhone.
• The VPN is installed but its devices don't load. Nuticast reads Tailscale and Netbird devices from their command line tools. If yours live somewhere unusual, set the path under Settings → CLI path and use Test device list.
• ZeroTier never lists devices. That's expected: ZeroTier's tools don't expose other devices' addresses. Paste the iPhone's ZeroTier IP from ZeroTier Central (set a static IP for it so it doesn't change).
• The iPhone isn't found while adding. It has to be on the Mac's Wi‑Fi (or plugged in) with wireless debugging already set up in Xcode.

Network changes and sleep

• When the Mac's address changes (new Wi‑Fi, VPN reconnect), active bridges restart by themselves.
• Bridges that were on come back when you reopen Nuticast, if the license is valid. Turn on Launch at Login to have them back after a restart.
• The Mac has to stay awake and online for the bridge to work. If a bridge shows Error after the Mac wakes up, switch it on again.

License

• Where to activate: in the app, Settings → License. Or in Terminal: nuticast license activate (asks for the key with hidden input).
• How many Macs: a Personal license works on 3 Macs. A Team license works on as many Macs as seats bought. Reinstalling on the same Mac doesn't use another slot.
• "Activation limit reached. Deactivate one first." Deactivate a Mac you no longer use: Settings → License → Deactivate on that Mac, or nuticast license deactivate. Do this while the Mac is online so the slot is freed. No access to the old Mac? Email license@nuticast.com.
• "License not found." Check the key for typos. It's in the email you got after buying and on the order page.
• "This license key isn't for Nuticast." The key is from another product.
• "Your license has expired." The yearly subscription ended or a renewal payment failed. Renew, or email license@nuticast.com.
• "Couldn't reach the license server." Check the Mac's internet connection. A license that was checked recently keeps working offline for up to 7 days; after that Nuticast needs to go online once.
• The command line or an AI agent says there's no license, but the app is licensed. macOS may be showing a Keychain prompt on the Mac. Choose Always Allow.

Logs and support

• Each device's page has a Log with recent events. The menu bar shows the latest lines.
• The full log is at ~/Library/Application Support/Nuticast/diagnostics.log. From Terminal: nuticast logs (--user for the short version, -f to follow).
• Settings → Support → Send diagnostics zips the log and opens a prefilled email for you to review and send. It includes the app and macOS versions, the Mac's name, hardware ID and local address, your saved devices and mesh VPNs, and the last 4 characters of your license key, never the full key.

Command line exit codes

More on driving Nuticast from scripts and agents: AI agents (MCP).

Common questions

Why does Nuticast refuse to bridge when the iPhone is on the same Wi‑Fi? Because Xcode already sees the phone there, and a second path to the same phone would conflict with it. Nuticast is only needed when the iPhone is on a different Wi‑Fi.

Does Nuticast work when the iPhone is on cellular? No. The iPhone has to be on Wi‑Fi. Any Wi‑Fi works, including another phone's Personal Hotspot.

What does Scan port do? It checks the iPhone's saved wireless debugging port over the mesh VPN and, if the port moved, searches for the new one and saves it.

How many Macs can use one license? A Personal license works on 3 Macs. A Team license works on one Mac per seat. Deactivate a Mac in Settings → License to free its slot.

What if the Mac can't reach nuticast.com? The license keeps working for up to 7 days after its last successful check. After that, Nuticast needs to reach the license server once before it starts new bridges.

Can I use the menu bar app and the nuticast command at the same time? Yes, but not for the same device. Opening the app clears bridges started from the command line, so pick one per session.

Still stuck? Email hello@nuticast.com with the log from Settings → Support → Send diagnostics.