Common Issues & Solutions

This guide covers the most frequently encountered issues and their solutions.

Discovery Issues

Devices Not Appearing in Radar

Problem: Can't see other devices even though AirShare is running on both

Possible Causes & Solutions:

1. Different Networks

• ✅ Check: Both devices must be on the exact same network
• Verify: WiFi network name matches on both devices
• Note: Guest networks are often isolated from main network

2. Firewall Blocking

Windows:

1. Windows Security → Firewall & network protection
2. Allow an app through firewall
3. Find AirShare and check Private and Public networks
4. If not listed, click "Change settings" → "Allow another app"
5. Browse to AirShare.exe and add it

macOS:

1. System Settings → Network → Firewall
2. Click Firewall Options
3. Ensure AirShare is allowed
4. Or temporarily disable firewall to test

Linux (UFW):

sudo ufw allow from 192.168.0.0/16 to any port 59875:59925 proto udp
sudo ufw allow from 10.0.0.0/8 to any port 59875:59925 proto udp
sudo ufw reload

3. Router Blocking Multicast (mDNS)

• Some routers have "multicast filtering" or "AP isolation" enabled
• Check: Router admin panel → Wireless Settings
• Disable: AP Isolation, Multicast Filtering, or Client Isolation
• Consumer routers: Usually fine
• Enterprise/Hotel WiFi: Often blocks multicast

4. VPN Interference

• VPNs can hide local network devices
• Solution: Disconnect from VPN temporarily
• Alternative: Use split-tunneling to allow local traffic

5. Visibility Settings

• Check Settings → Privacy → Visibility
• Ensure "Visible to others" is enabled

6. Waiting for Discovery

• Auto-discovery happens every 5 seconds
• Wait: 10-15 seconds before assuming failure
• Try: Click refresh button in Radar

Devices Appear Then Disappear

Problem: Device shows briefly then vanishes from Radar

Solutions:

1. Network Instability
   • Check WiFi signal strength
   • Move closer to router
   • Switch from 2.4 GHz to 5 GHz
2. Power Saving Settings
   • Disable "Turn off WiFi to save power"
   • Keep computer plugged in
   • Prevent sleep during transfers
3. Network Switching
   • Device may be switching between networks
   • Disable automatic network switching
   • Stick to one network

Transfer Issues

Transfer Fails Immediately

Problem: Transfer fails right after clicking Send

Solutions:

1. File Size Limit (Free Tier)
   • Free tier: 200 MB max
   • Check file size before sending
   • Split large files or upgrade to Pro
2. Insufficient Disk Space
   • Receiver doesn't have enough space
   • Check available space on receiving device
   • Free up space or change download location
3. File Type Blocked
   • Receiver may have file type restrictions
   • Check Settings → Privacy → File Types
   • Disable blocking or add allowed extensions
4. Connection Lost
   • Network disconnected during setup
   • Check network connection on both devices
   • Restart transfer

Transfer Slow or Stuttering

Problem: Transfer speed is very slow or keeps pausing

Solutions:

1. Network Congestion
   • Close other network-intensive apps
   • Stop downloads, streaming, video calls
   • Pause cloud sync services (Dropbox, OneDrive)
2. WiFi vs Ethernet
   • Use wired Ethernet for best speed
   • If WiFi, use 5 GHz instead of 2.4 GHz
   • Get closer to router
3. Other Device Activity
   • Sender/receiver running heavy tasks
   • Close unnecessary apps
   • Check Task Manager/Activity Monitor
4. Old Hardware
   • Older computers may have slower network cards
   • Check network adapter speed
   • Consider hardware upgrade

Expected Speeds:

Transfer Stuck at 0% or 99%

Problem: Progress bar doesn't move or stuck near completion

Solutions:

Stuck at 0%:

• Wait 30 seconds (may be calculating hash)
• Check network connection
• Cancel and retry

Stuck at 99%:

• AirShare is verifying file integrity (SHA-256 hash)
• This can take 10-30 seconds for large files
• Don't cancel - let it finish

Files Arrive Corrupted

Problem: Received files won't open or are damaged

Solutions:

1. Extremely Rare: AirShare uses SHA-256 verification
2. Likely Causes:
   • Source file was already corrupted
   • Disk errors on receiving device
   • Antivirus modified file
3. Steps:
   • Ask sender to verify source file
   • Try receiving to different drive
   • Run disk check utility
   • Temporarily disable antivirus

Connection Issues

"Connection Refused" Error

Problem: Error when trying to send files

Solutions:

1. Receiver Not Ready
   • Ensure AirShare is running on receiver
   • Check receiver is online in Radar
   • Wait a few seconds and retry
2. Port Blocked
   • Firewall blocking QUIC ports (59875-59925)
   • Add firewall exceptions
   • Check corporate network policies
3. Network Mismatch
   • Devices may be on different subnets
   • Check IP addresses (should be similar, e.g., 192.168.1.x)
   • Contact network administrator

"Timeout" Error

Problem: Transfer times out waiting for recipient

Solutions:

1. Recipient Didn't Respond
   • Default timeout: 60 seconds
   • Recipient must click Accept/Decline
   • Notify recipient before sending
2. Notification Missed
   • Enable sound notifications
   • Check system notifications are enabled
   • Keep AirShare window visible

Installation Issues

macOS: "App is Damaged" Error

Problem: macOS says AirShare is damaged and can't be opened

Solution:

# Remove quarantine attribute
xattr -cr /Applications/AirShare.app

# Then open normally

Why This Happens: macOS Gatekeeper protection for unsigned apps.

Windows: SmartScreen Warning

Problem: "Windows protected your PC" message

Solution:

1. Click "More info"
2. Click "Run anyway"
3. Or right-click installer → Properties → Unblock → Apply

Why This Happens: AirShare doesn't have expensive EV code signing certificate.

Linux: AppImage Won't Run

Problem: Double-clicking AppImage does nothing

Solutions:

# Make executable
chmod +x AirShare_*.AppImage

# Run from terminal to see errors
./AirShare_*.AppImage

# If FUSE error, extract and run
./AirShare_*.AppImage --appimage-extract
./squashfs-root/AppRun

Linux: "No mDNS Daemon" Error

Problem: Discovery doesn't work, mDNS errors in logs

Solution:

# Debian/Ubuntu
sudo apt-get install avahi-daemon
sudo systemctl enable --now avahi-daemon

# Fedora/RHEL
sudo dnf install avahi
sudo systemctl enable --now avahi

# Arch Linux
sudo pacman -S avahi
sudo systemctl enable --now avahi-daemon

Performance Issues

High CPU Usage

Problem: AirShare using excessive CPU

Solutions:

1. During Transfer: Normal - CPU used for encryption/hashing
2. When Idle: Not normal
   • Restart AirShare
   • Check for stuck transfers
   • Update to latest version
   • Report bug if persists

High Memory Usage

Problem: AirShare using too much RAM

Solutions:

1. Large Transfers: Temporarily normal (uses buffer)
2. Memory Leak: If RAM keeps growing
   • Restart AirShare
   • Update to latest version
   • Report bug with debug logs

Database Slow

Problem: History tab is slow to load or search

Solutions:

1. Optimize Database:
   • Settings → Storage → Optimize Database
   • This vacuums and compacts SQLite
2. Clear Old History:
   • Settings → Storage → History Retention
   • Auto-delete old entries
3. Nuclear Option:
   • Settings → Storage → Clear All History
   • Starts fresh (can't be undone)

License Issues

"Invalid License Key" Error

Problem: License key not accepted

Solutions:

1. Check for Typos:
   • Copy-paste the entire key
   • Don't add spaces or line breaks
   • Key is case-sensitive
2. Already Activated:
   • Each license is for one device only
   • Deactivate on other device first
   • Or purchase additional licenses
3. Expired License:
   • 1-year Pro licenses expire
   • Check expiration date in email
   • Renew or upgrade to lifetime

Free Tier Limits

Problem: "Daily transfer limit exceeded" or "File too large"

Solutions:

File Size Limit (200 MB):

• Split large files into parts
• Compress files before sending
• Upgrade to Pro for unlimited

Daily Transfer Limit (10 transfers):

• Wait until tomorrow (resets at midnight)
• Prioritize important transfers
• Upgrade to Pro for unlimited

Update Issues

Update Check Fails

Problem: Can't check for updates

Solutions:

1. No Internet: Updates require internet
2. Firewall: Allow HTTPS to github.com
3. Manual Check: Visit releases page directly

Update Installation Fails

Problem: Update downloads but won't install

Solutions:

1. Close AirShare Completely:
   • Quit from tray icon
   • Check Task Manager/Activity Monitor
   • Kill process if needed
2. Manual Update:
   • Download installer from releases page
   • Install over existing version
   • Settings and history are preserved

Diagnostic Tools

Enable Debug Logging

To diagnose issues:

1. Settings → Advanced → Logging
2. Enable "Debug logging"
3. Set log level to "Debug" or "Trace"
4. Reproduce the issue
5. Settings → Advanced → "View Logs"
6. Share relevant logs when reporting bugs

Network Diagnostics

Check network status:

1. Radar → Tools → "Network Diagnostics"
2. View:
   • Local IP address
   • Active QUIC port
   • mDNS status
   • Discovered devices

Check Firewall Rules

Windows:

# Check if AirShare is allowed
Get-NetFirewallApplicationFilter -Program "*airshare*" | Get-NetFirewallRule

macOS:

# Check application firewall status
/usr/libexec/ApplicationFirewall/socketfilterfw --getappblocked /Applications/AirShare.app

Linux (UFW):

# Check firewall status
sudo ufw status verbose

Getting Help

If you've tried the solutions above and still have issues:

Before Reporting

1. Update to Latest Version: Many bugs are already fixed
2. Enable Debug Logging: Helps us diagnose
3. Gather Information:
   • AirShare version
   • Operating system and version
   • Network setup (WiFi/Ethernet, router model)
   • Steps to reproduce

Report a Bug

1. Visit GitHub Issues
2. Search existing issues first
3. Create new issue with:
   • Clear title
   • Detailed description
   • Steps to reproduce
   • Expected vs actual behavior
   • Debug logs (if applicable)
   • Screenshots/videos (if helpful)

Community Help

• GitHub Discussions
• FAQ Page

Next Steps