DeckPilot

Connection Troubleshooting

Step-by-step guide to fix connection issues between your iPhone/iPad and Mac.

Most Common Causes

Mac Local Network permission

Toggle OFF then ON in System Settings

Different Wi-Fi networks

Both devices on the same network

Mac firewall blocking

Allow DeckPilot in Firewall options

VPN active on either device

Disconnect VPN

Hotel/office Wi-Fi isolation

Use USB cable instead

iOS Local Network denied

Enable in Settings > Privacy

1

Check the basics

Both devices are on the same Wi-Fi network
DeckPilot is running on your Mac (look for the icon in the menu bar)
Your Mac is awake (not sleeping or lid closed)
You're NOT on a VPN on either device
If you're on a hotel, office, or public Wi-Fi, the network may block device-to-device communication. Try connecting your iPhone to your Mac via USB cable instead — it works automatically over the cable.
2

Check iPhone/iPad permissions

iOS requires apps to have Local Network permission to discover devices.

  1. Open Settings on your iPhone/iPad
  2. Go to Privacy & Security → Local Network
  3. Find DeckPilot and make sure it's ON
If DeckPilot isn't listed, open the DeckPilot app — iOS will prompt you for permission. If you accidentally denied it, you can enable it here.
3

Check Mac permissions (macOS 15+)

macOS 15 (Sequoia) and later requires apps to have Local Network permission. This is a separate permission from the firewall.

  1. Open System Settings on your Mac
  2. Go to Privacy & Security → Local Network
  3. Find DeckPilot in the list
  4. If it's ON but not working: toggle it OFF, wait 3 seconds, toggle ON
  5. Quit DeckPilot and relaunch it
Known macOS bug: macOS has a known bug where this permission can silently reset after a restart. If pairing suddenly stops working after restarting your Mac, repeat this step.
If DeckPilot isn't listed in Local Network settings, delete the app from Applications, reinstall from the DMG, and launch it — macOS will prompt you for permission.
4

Check Mac firewall

  1. Open System Settings → Network → Firewall
  2. If the firewall is ON, click Options
  3. Make sure DeckPilot is listed and set to Allow incoming connections
If "Automatically allow downloaded signed software" is enabled (it is by default), DeckPilot should be auto-allowed. If not, add it manually.
5

Mac doesn't appear in the server list

If your iPhone can't find the Mac at all (empty server list), try these:

  1. On your Mac, click the DeckPilot menu bar icon. It should show "Server ready on port XXXX". If it shows a warning, the server didn't start.
  2. Try quitting and relaunching DeckPilot on both devices
  3. Toggle Wi-Fi off and on on your iPhone
  4. Make sure both devices are on the same Wi-Fi band (some routers have separate 2.4GHz and 5GHz networks)
  5. If your router has AP/Client Isolation enabled (common on guest networks), disable it or use a different network
  6. Try connecting via USB cable — plug your iPhone into your Mac, it connects automatically
6

QR code pairing doesn't work

If tapping the Mac name or scanning the QR code shows "Connecting..." but never completes:

  1. This is almost always the Mac's Local Network permission (Step 3 above)
  2. The Mac server is running but macOS is silently blocking incoming connections
  3. Toggle the Local Network permission OFF → wait 3 seconds → ON, then relaunch DeckPilot
7

Was connected before, now won't connect

If pairing worked before but stopped after a Mac restart or update:

  1. Check Step 3 — macOS may have reset the Local Network permission after the restart
  2. On your Mac menu bar, click DeckPilot → Diagnostics → Clear All Trusted Devices
  3. On your iPhone, go to the pairing screen and tap the Mac name to re-pair
  4. Your Mac will show an Allow prompt — tap it
8

Nuclear option — fresh start

If nothing else works, start completely fresh:

  1. iPhone: Delete DeckPilot → Reinstall from App Store → Launch → Grant all permissions
  2. Mac: Quit DeckPilot → Delete from Applications → Reinstall from DMG → Launch → Grant all permissions
  3. Pair again — tap the Mac name or scan the QR code
9

Still not working?

Send us a bug report with your connection logs — we can diagnose the issue remotely.

  1. On your iPhone, open DeckPilot → tap the status dot (or reconnecting overlay) → tap Contact Support
  2. Your connection logs are automatically attached to the message
  3. Describe what you see and we'll get back to you

Or email us directly at [email protected]