AirPinpoint Troubleshooting Guide

Comprehensive troubleshooting steps for common AirPinpoint setup issues

Troubleshooting Guide

When setting up AirPinpoint, you might encounter various issues. This guide will help you resolve them:

Before You Begin

Please verify these requirements before proceeding:

Active iCloud account with FindMy enabled
FindMy app opened at least once after login
Location Services enabled
Full Disk Access enabled for Terminal/App
MacOS version 11.0 (Big Sur) through 14.x
Xcode Developer Tools installed

Common Error Types

1. BeaconStore Key Issues

These occur when the system cannot properly access the encryption keys needed to read your FindMy data.

Most Common Causes:

FindMy Not Initialized
- FindMy app hasn't been opened after iCloud login
- BeaconStore keychain item not yet created
- Most common even if iCloud is signed in
Keychain Access Issues
- Script lacks permissions to access keychain
- Keychain is locked
- Terminal app missing Full Disk Access
iCloud Account Problems
- Different iCloud account in System Settings vs setup
- BeaconStore key exists but for wrong account

Solutions:

Open FindMy app and wait ~1 minute
Sign out and back into iCloud
Verify Terminal has Full Disk Access:
- System Settings → Privacy & Security → Full Disk Access
- Enable for Terminal
Unlock your keychain:

security unlock-keychain login.keychain

2. File Access Issues

Occurs when the script cannot read necessary system files or create output directories.

Possible Causes:

Missing Full Disk Access permissions
Incorrect file permissions
System Integrity Protection blocking access
Disk space issues

Solutions:

Grant Full Disk Access to Terminal
Check directory permissions:

ls -la ~/Library/com.apple.icloud.searchpartyd

Verify disk space:

df -h /

3. Decryption Failures

Occurs when files exist but cannot be properly decrypted.

Possible Causes:

Corrupted plist files
Invalid encryption keys
Incomplete FindMy initialization
File system permission issues

Solutions:

Reset FindMy:

killall "FindMy"
killall "searchpartyd"
open -a "FindMy"

Wait 1-2 minutes for FindMy to reinitialize
Check file integrity:

plutil -lint ~/Library/com.apple.icloud.searchpartyd/OwnedBeacons/*

4. System Requirements Issues

Occurs when your system doesn't meet the basic requirements.

Required Configuration:

MacOS 11.0 or higher (up to 14.x)
Xcode Command Line Tools
Active iCloud account
FindMy enabled and initialized
Location Services enabled
Full Disk Access granted

Verification Steps:

Check MacOS version:

sw_vers -productVersion

Verify iCloud status:

defaults read MobileMeAccounts

Check FindMy service:

defaults read com.apple.FindMy

Verify Location Services:

/usr/bin/defaults read /var/db/locationd/Library/Preferences/ByHost/com.apple.locationd

Advanced Troubleshooting

Keychain Debugging

If you're experiencing persistent keychain issues:

Check BeaconStore existence:

security find-generic-password -l "BeaconStore" -w 2>/dev/null || echo "BeaconStore not found"

Verify keychain permissions:

security show-keychain-info login.keychain

File System Debugging

For file access issues:

Check critical directories:

ls -la ~/Library/com.apple.icloud.searchpartyd/OwnedBeacons
ls -la ~/Library/com.apple.icloud.searchpartyd/BeaconNamingRecord

Verify file permissions:

sudo ls -la /var/db/locationd/Library/Preferences/ByHost/

Process Verification

To ensure all required services are running:

Check FindMy processes:

ps aux | grep -i "FindMy\|searchpartyd"

Verify iCloud services:

launchctl list | grep icloud

What Happens Next?

After successful setup:

Pro Tier: Your configured AirTags will appear in your dashboard
Business Tier: Your pre-configured AirTags will be mailed to you and will already be visible

Refresh the page to see your devices!

Still Having Issues?

If you've tried these solutions and still experience problems:

Check system logs:

log show --predicate 'subsystem == "com.apple.findmy"' --last 30m

Contact our support team:

Email: support@airpinpoint.com
Include:
- Error messages
- MacOS version
- Steps already attempted
- System log output

Remember: Most setup issues can be resolved by ensuring proper system permissions and a clean FindMy initialization.

Note: This setup process only needs to be completed once. After successful setup, your FindMy devices will be continuously monitored without any additional configuration needed.

Important: If you recently changed your Apple ID password, you may need to sign out and back into iCloud to refresh keychain access.

Authorize Keychain Access

You should see a popup asking for your keychain password, asking for access to your FindMy devices (aka Beacons).

Keychain Access Popup

Enter your Mac's password when prompted to grant access.
If you do not see this, make sure Passwords & Keychain is enabled in System Preferences -> iCloud -> Passwords & Keychain

Note: This setup process only needs to be completed once to enable reading of your FindMy devices. This is a one-time setup step - nothing will be kept running on your Mac. Important:

If you recently changed your Apple ID password, you may need to sign out and back into iCloud to refresh keychain access.

Full Disk Access is required to read protected system files containing FindMy data.

What Happens Next?

After successful setup:

Pro Tier: Your configured AirTags will appear in your dashboard after setup
Business Tier: Your pre-configured AirTags will be mailed to you and will already be visible in your dashboard Refresh the page and run the quickstart command to see the location of one of your devices!

Troubleshooting

Keychain Access: Ensure your Keychain is unlocked. If your Mac prompts for a password/keychain login, accept it so the setup process can read necessary credentials.
Swift Installation: Ensure Swift is installed on your system. Run swift --version to verify. Install via Xcode or the official Swift installer if needed.
Full Disk Access: Verify Terminal has Full Disk Access permissions in System Preferences. This is required to access protected FindMy data files.
iCloud Account: Confirm you're signed into your iCloud account on this Mac. "FindMy" must be enabled.
Location Services: Ensure Location Services is enabled. (FindMy requires this to work)
Xcode: Ensure you have Xcode dev tools installed. This is required to read the FindMy device keys.
MacOS Version: Ensure your MacOS version is 11.13 (Big Sur) or higher. However, some people have reported issues with versions 15.0 and higher. We recommend 11-14.
Miscellaneous: Some users have reported that signing into icloud in safari/chrome unblocked them. We have not been able to reproduce this, but it may be worth trying.

If you encounter any issues during setup, please contact our support team: support@airpinpoint.com

AirPinpoint Mac Access Location Tracking