Troubleshooting

Quick triage table

Pick the symptom that matches your problem and jump to the section.

Identity didn't generate

You tap Create in the New Signer sheet, Face ID prompts, and after biometrics succeed the Status banner shows an error like Secure Enclave is unavailable on this device. or Failed to save the Secure Enclave key reference: <reason>.

Common causes and fixes:

• No device passcode set. The Secure Enclave refuses to generate keys with userPresence access if the device has no passcode. Open Settings → Face ID & Passcode (or Touch ID & Passcode) and set a passcode. Re-try the provision.
• Passcode just changed. iOS occasionally requires a fresh authentication after a passcode change. Lock the phone, unlock it with Face ID and the new passcode, then re-try.
• Device is in a configuration profile lockdown. Some MDM-managed devices have policies that disable Secure Enclave key creation for unmanaged apps. Check with your IT admin or, on personal devices, Settings → General → VPN & Device Management.
• Insufficient storage. The Keychain reference is small but the metadata file grows with each identity. Free up space if your iPhone is critically low.
• Stale state from a previous failed attempt. Force-quit the app from the App Switcher, reopen, and re-try. App-internal state can occasionally desynchronize from Keychain state.

If the error persists across all of the above, restart the iPhone. If it still persists after a restart, your Secure Enclave may have a hardware fault; contact Apple Support.

Mac shows disconnected

The Transport section on the iPhone reports Connected to <Mac> and then drops to Advertising, or vmuxAgent's menu bar icon shows the iPhone offline.

Causes:

• You walked away from your Mac. Multipeer Connectivity has a working range similar to AirDrop — about 10 meters with line of sight, less through walls. Move the iPhone closer.
• Wi-Fi network changed. Switching SSIDs (home to office, leaving Wi-Fi for cellular) breaks the Multipeer link. The iPhone re-advertises automatically, but vmuxAgent on the Mac may need a moment to re-discover. Open vmuxAgent's menu and re-pair if it doesn't reconnect within ten seconds.
• iPhone went into Low Power Mode and suspended the app. The Multipeer transport stops when the app is fully suspended. APNs push wake will recover it on the next sign request from the Mac, but the visible Transport status will lag behind.
• iOS killed the app for memory pressure. Rare. Symptoms include both the Multipeer session and APNs token registration disappearing. Reopen the app.

Fixes in order from cheapest to most thorough:

1. Open RemoteSignerPhone — that alone often re-establishes the link.
2. Force-quit (App Switcher → flick away) and reopen. This re-bootstraps Multipeer and re-registers for APNs.
3. Toggle Wi-Fi off and on under Control Center.
4. From the Mac, quit and relaunch vmuxAgent.
5. Reboot the iPhone. Last resort.

Push notification missing

You ran ssh on the Mac, vmuxAgent forwarded the request, and the iPhone never showed a Sign Request notification.

Walk through this checklist:

• Open the app. If RemoteSignerPhone was force-quit (manually swiped away), iOS suppresses APNs delivery. You must launch it once before iOS will deliver pushes. After the next launch, the app re-registers and resumes normal operation.
• APNs Token: Registered. Open the app and look at Transport. If Not registered, the iPhone has no internet, or registration failed. Connect to a working network and relaunch.
• Notifications permission. Settings → Notifications → RemoteSigner. Allow Notifications must be on. Time Sensitive Notifications must be on. Banner Style: Persistent or Temporary, your preference.
• Focus mode. Settings → Focus → (active mode) → Apps must include RemoteSigner in the allowed list. Time-sensitive notifications can pierce most Focus modes only if the app is allowed.
• iPhone has internet. APNs requires Wi-Fi or cellular. Captive portals you haven't logged into count as no-internet.
• vmuxAgent has the current device token. The iPhone sends its token to the Mac when they pair. If you reinstalled the app, generated a new token, but haven't paired with vmuxAgent since, the Mac is still using the old token. Force-quit and relaunch RemoteSignerPhone, then ensure vmuxAgent reconnects.

If push is still missing and you need to test a sign request urgently, keep RemoteSignerPhone in the foreground while making the SSH connection. Foreground operation does not depend on push at all.

Biometric repeatedly rejected

Face ID or Touch ID keeps failing during the Sign Request approval flow.

• Face ID works elsewhere? If yes, the issue is local to RemoteSignerPhone. If no, fix Face ID first (clean the front camera, re-enroll your face in Settings → Face ID & Passcode).
• Wear something that covers your face? Glasses, masks, hats, sunglasses — Face ID handles these but accuracy drops in marginal lighting.
• Recently re-enrolled biometrics? iOS occasionally requires a passcode authentication after biometric re-enrollment to refresh the Secure Enclave's authentication context. Tap Use Passcode in the prompt and enter your device passcode once; subsequent prompts should use Face ID normally.
• Passcode prompt comes up instead of biometrics? This happens after a few failed Face ID attempts in a row, after restart, or if the device hasn't been unlocked recently. Use the passcode; you'll be back to biometrics on the next prompt.
• Multiple failed attempts in a row lock you out. iOS requires a passcode after five failed attempts. Once the passcode unlocks the device, biometrics resume.

If Face ID works for unlocking the iPhone but consistently fails inside RemoteSignerPhone, force-quit and reopen the app. The Local Authentication framework can occasionally get into a weird state that a relaunch clears.

Signing prompt didn't appear

The Mac says it sent a sign request, but no Sign Request sheet appeared on the iPhone.

• App was suspended in deep background. APNs wake should have nudged it. See push notification missing — same root cause family.
• The notification arrived but you didn't see it. Check Notification Center. Pull down from the top and look for "SSH Sign Request". Tap it to open the app and see the sheet.
• The iPhone is paired with a different device. If a Vision Pro and a Mac are both trying to talk to the iPhone simultaneously, only one can be paired at a time. Whichever device's session won the race gets the sign request; the other gets nothing. Disconnect from the other device first.
• The identity for that key is disabled. Open the relevant identity in RemoteSignerPhone and check the Enabled toggle. A disabled identity refuses sign requests with The selected identity is disabled. and the failure surfaces on the requester, not as a prompt.
• The public key isn't in the iPhone's identity list at all. If you previously deleted an identity but its public key is still in the server's authorized_keys, the SSH client may try to use it; the iPhone has no matching identity and refuses. The Mac will see "agent refused operation". Remove the stale public key from authorized_keys.

Key disappeared after iOS update

After upgrading iOS or restoring from a backup, an identity exists in the Signers list but tapping Verify Secure Enclave Access fails with The stored Secure Enclave key is invalid.

This is by design. Apple invalidates Secure Enclave-protected Keychain items in a few scenarios:

• iCloud restore onto a new device. The old chip's key cannot be used on a new chip.
• Erase All Content and Settings followed by a restore. Same reason.
• Major iOS upgrade in some edge cases. Rare but documented.
• Disabling the device passcode (this purges all Secure Enclave keys immediately).

There is no recovery. The metadata record is intact (label, fingerprint, public key) but the underlying Secure Enclave reference is dead. Two paths forward:

• Delete and re-create. Open the dead identity, tap Delete Identity, confirm. Provision a new identity with the same label. Then update the public key in your servers' authorized_keys to the new one.
• Just create a new identity alongside. If you'd like to keep the dead record visible until you've migrated all servers, leave it disabled and provision a new one. Migrate authorized_keys entries server by server, then delete the dead identity.

There's no way to "transfer" a Secure Enclave key between iPhones. The hardware binding is the security guarantee.

Decoding error messages

When to escalate

If none of the above resolves your problem, gather the following before reaching out:

• iOS version (Settings → General → About → iOS Version).
• iPhone model.
• Whether the issue reproduces with the app foregrounded (rules out background/push problems).
• Whether the issue reproduces with a freshly provisioned identity (rules out key-specific corruption).
• The exact text of any error in the Status banner.

Related

• Background wake — full APNs flow if push is the suspected layer.
• Pairing and discovery — Multipeer states for connection-level issues.
• Security — why Secure Enclave keys are non-recoverable, with threat model context.