Troubleshooting
This page covers common issues and their solutions, organized by symptom. If your problem is not listed here, check the documentation for the specific source or setting involved.
Messages are not appearing¶
The board is running but no messages are flipping in.
| Check | Details |
|---|---|
| Source is enabled | Open Settings > Sources and verify that at least one source is toggled on. |
| Green indicator | An active source shows a green indicator in the source list. If the indicator is red or absent, the source is not connected. |
| Authentication is valid | For social sources (Mastodon, Bluesky, Threads), your token may have expired. Sign out and sign back in. |
| Feed URL is correct | For RSS, verify the URL points to a valid feed. Try opening it in a browser to confirm it returns XML. |
| Messages in queue | If all messages have already been displayed and no new ones have arrived, the board will appear idle. Swipe left/right (or use the Siri Remote) to revisit previous messages. |
Test with Manual Input
On iPad, use Settings > Sources > Manual Input to type a test message. If it appears on the board, the display is working and the issue is with your configured source.
No sound¶
Flap animations are playing but you cannot hear the clicking sound.
| Check | Details |
|---|---|
| Enable Sounds | Open Settings > Sound and make sure Enable Sounds is toggled on. |
| Silent mode | On iPad, check that the device is not in Silent Mode (check the physical mute switch or Control Center). |
| Volume | Ensure the device volume is above zero. On iPad, use the volume buttons. On Apple TV, use the Siri Remote volume buttons. |
| TV not muted | On Apple TV, the TV itself may be muted or at zero volume independently of the Siri Remote. Check the TV's own volume controls or remote. |
Apple TV audio
Apple TV audio is routed through HDMI to your TV or receiver. If you hear no sound at all from any app, the issue is likely with the TV's audio settings, not Arrivals.
Local Server is not accessible¶
You have enabled the Local Server but cannot reach it from another device.
| Check | Details |
|---|---|
| Server is enabled | Open Settings > Sources > Local Server and confirm the toggle is on. The status should show "Running". |
| Same network | The device sending requests and the device running Arrivals must be on the same local network (same Wi-Fi, or wired + wireless on the same subnet). |
| Port is not blocked | The default port is displayed in the Local Server settings. Some networks block non-standard ports. Try changing to a common port like 8080. |
| Firewall | Corporate or managed networks may run firewalls that block device-to-device communication. Check with your network administrator. |
| Try a different port | If the default port is in use by another app, change it in Settings > Sources > Local Server > Port. |
Public networks
The Local Server is designed for trusted local networks. It does not use authentication. Do not expose it to the public internet.
Mastodon authentication fails¶
You cannot sign in to your Mastodon instance.
| Check | Details |
|---|---|
| Instance URL is correct | Enter just the hostname (e.g., mastodon.social), not a full URL with https:// or a trailing slash. |
| Instance is online | Try opening your instance in a browser to verify it is reachable. |
| Local Server for tvOS | On Apple TV, QR authentication requires the Local Server. Make sure it is enabled, or let Arrivals enable it automatically during sign-in. |
| Try the manual flow | If QR scanning fails, use the Enter Manually option below the QR code. See QR Authentication. |
| Re-authorize | Some instances revoke OAuth tokens after extended inactivity. Sign out of the source and sign back in. |
Bluesky authentication fails¶
Login is rejected or the timeline does not load.
| Check | Details |
|---|---|
| Use an App Password | Bluesky requires an app-specific password, not your main account password. Generate one at bsky.app under Settings > App Passwords. |
| Check your handle | Enter your full handle (e.g., user.bsky.social), not just the username. |
| Token expired | Arrivals automatically refreshes tokens, but if it fails, remove and re-add the account. |
Calendar events are not showing¶
The Calendar source is enabled but no events appear on the board.
| Check | Details |
|---|---|
| Calendar access permission | Arrivals needs permission to access your calendars. Go to your device's Settings > Privacy & Security > Calendars and make sure Arrivals is allowed. |
| Calendars are selected | In Settings > Sources > Calendar, check that at least one calendar is selected. If no calendars are checked, no events will be displayed. |
| Events within lookahead window | The Calendar source only displays events within the configured lookahead window (e.g., the next 24 hours). If your next event is further out, it will not appear yet. Increase the lookahead window to see events further in the future. |
| All-day events | Verify whether Show All-Day Events is enabled if you expect all-day events to appear. |
Weather is not updating¶
The Weather source is enabled but shows stale or no data.
| Check | Details |
|---|---|
| Location permission | Weather uses your device's location to fetch conditions. Go to your device's Settings > Privacy & Security > Location Services and ensure Arrivals has access (at least "While Using"). |
| Manual location | If you prefer not to grant location access, set a manual location in Settings > Sources > Weather. Enter a city name or coordinates. |
| 15-minute update cycle | Weather data refreshes approximately every 15 minutes. This is normal --- WeatherKit rate limits apply, and conditions do not change faster than this. |
| WeatherKit availability | Apple WeatherKit may occasionally experience service disruptions. If weather stops updating entirely, check Apple System Status. |
Board appears frozen¶
The board is visible but nothing is changing --- no flipping, no new messages.
| Check | Details |
|---|---|
| App is in foreground | A backgrounded app pauses all animations and source connections. On iPad, make sure Arrivals is the active app. On Apple TV, press any button on the Siri Remote. |
| No messages in queue | If all configured sources have been consumed and no new messages have arrived, the board has nothing to display. Wait for new content or add additional sources. |
| Try swiping | Swipe left or right on the iPad screen (or on the Siri Remote touch surface) to manually advance to the next message. If the board responds, it was simply waiting for the next message cycle. |
| Restart the app | If none of the above resolves the issue, force-quit Arrivals and reopen it. On Apple TV, double-press the TV button, swipe up on Arrivals, then relaunch. |
Background behavior
Arrivals pauses all network activity and animations when it is not the active app. This is normal iOS and tvOS behavior. The app resumes automatically when brought back to the foreground, and sources will reconnect and fetch any missed messages.
iCloud sync is not working¶
Settings or sources configured on one device are not appearing on another.
| Check | Details |
|---|---|
| Same iCloud account | Both devices must be signed in to the same iCloud account. |
| iCloud Drive enabled | Go to your device's Settings > [Your Name] > iCloud > iCloud Drive and make sure it is enabled. |
| Arrivals iCloud access | On each device, ensure Arrivals is allowed to use iCloud Drive in Settings > [Your Name] > iCloud > Apps Using iCloud. |
| Network connection | iCloud sync requires an active internet connection on both devices. |
| Give it time | iCloud sync can take a few minutes, especially after initial setup. If changes do not appear immediately, wait and check again. |
General tips¶
Check the source indicator
Every source in Settings > Sources shows a colored indicator:
- Green --- connected and receiving data.
- Red --- disconnected or error.
- No indicator --- source is disabled.
This is the fastest way to diagnose whether a source is working.
Restart as a last resort
If an issue persists after checking all of the above, force-quit and relaunch Arrivals. This resets all network connections, reconnects to streaming APIs, and re-fetches data from all active sources.
Still having trouble?¶
If none of the above solutions resolve your issue:
- Check that you are running the latest version of Arrivals.
- Restart the app completely (force-quit and reopen).
- Restart the device.
- Reinstall the app (your iCloud-synced settings will be preserved).