Herdr Native App Not Working on iOS: Fixes for Login, Sync & Crashes

What Causes This Issue

Since Herdr released its native iOS app, users in the Apple Support Community have reported a cluster of problems: authentication failures with Mastodon instances, timelines that refuse to refresh, push notifications that never arrive, and occasional crashes on launch. The issues appear widespread across multiple iOS versions and device models, suggesting they stem from the app’s initial native release rather than isolated device faults.

Common root causes include OAuth token mismatches during the web-to-native migration, background app refresh restrictions blocking timeline updates, keychain access conflicts when migrating credentials from the previous TestFlight or web version, and instance-specific API limitations that the new native client handles differently than the web wrapper.

Step-by-Step Fixes

1. Delete and reinstall the app, then re-authenticate from scratch. Users in the Apple Support Community confirm this as the most reliable fix. Remove Herdr completely (long-press → Remove App → Delete App), restart the iPhone, reinstall from the App Store, and sign into each Mastodon instance using the in-app browser flow. Do not restore from backup during reinstall.
2. Enable Background App Refresh for Herdr. Open Settings → General → Background App Refresh, ensure the master toggle is on, then scroll to Herdr and enable it. Without this, timeline sync and push notification registration fail silently.
3. Reset network settings to clear stale DNS or proxy caches. Settings → General → Transfer or Reset iPhone → Reset → Reset Network Settings. This resolves authentication handshake failures with certain Mastodon instances that use non-standard ports or custom domains.
4. Revoke and regenerate application tokens on each instance. Log into your Mastodon instance via web browser, navigate to Settings → Development → Your Applications, revoke any tokens named “Herdr” or “Herdr iOS”, then re-authenticate in the app. This clears OAuth scope mismatches introduced during the native transition.
5. Disable Low Power Mode and verify battery optimization. Low Power Mode aggressively throttles background network activity. Settings → Battery → Low Power Mode (off). Also check Settings → Battery → Battery Health & Charging → Optimized Battery Charging and ensure it’s not interfering with overnight sync.
6. Check instance compatibility and API version. Some smaller or older Mastodon instances run outdated API versions that the native client no longer supports. In Herdr, tap the instance avatar → Instance Info → check “API Version”. Versions below 2.8.0 may exhibit broken timelines or missing media.

Additional Solutions

Clear keychain entries manually if reinstall doesn’t work. Use the Shortcuts app with a “Run Script Over SSH” action (or a Mac with Apple Configurator) to delete Herdr’s keychain items: security delete-generic-password -s "Herdr" -a "your-username". This forces fresh token generation.

Test with a second Mastodon account on a known-good instance like mastodon.social. If the second account works, the problem is instance-specific — contact your instance admin about API rate limits or CORS headers blocking the new client’s user agent.

Toggle iCloud Keychain sync off and on. Settings → [Your Name] → iCloud → Passwords & Keychain → Sync this iPhone (off, wait 30 seconds, on). This resolves credential conflicts when Herdr shares keychain groups with the previous TestFlight build.

Update to the latest iOS point release. Several community reports note that iOS 17.6.1 and 18.0.1 include WebKit fixes that affect Herdr’s in-app authentication browser. Settings → General → Software Update.

Submit a diagnostic report from within the app. Herdr → Settings → Advanced → Send Diagnostic Log. This attaches device logs, API responses, and token state — critical for the developer to identify instance-specific regressions.

When to Contact Apple Support

Contact Apple Support if:

• The app crashes immediately on launch even after clean reinstall and iOS update — this may indicate a code-signing or entitlement issue requiring Apple’s distribution team.
• Push notifications fail entirely despite correct APNs configuration, Background App Refresh enabled, and Focus modes allowing Herdr — Apple can verify APNs token delivery for your device.
• Keychain operations return errSecAuthFailed or errSecItemNotFound consistently across apps — suggests keychain database corruption needing Apple’s tools.
• You suspect the App Store bundle is corrupted (checksum mismatch) — Apple can re-issue the download or escalate to the developer for a rebuild.

For all other issues — timeline gaps, media upload failures, account switching bugs — report directly to Herdr via their GitHub issues or Mastodon account. The developer responds faster than Apple for application-layer bugs.

FAQ

Why does Herdr say “Invalid instance” when I enter my server URL? The native app validates the instance’s /.well-known/nodeinfo and /api/v1/instance endpoints before allowing login. If your instance blocks these or returns malformed JSON, authentication fails. Ask your admin to verify both endpoints return 200 OK with valid Content-Type headers.

Can I run the TestFlight and App Store versions side by side? No. They share the same bundle identifier and keychain access group. Installing the App Store version overwrites the TestFlight build and migrates data — but the migration sometimes leaves orphaned tokens. Delete both before installing the App Store version clean.

My timeline shows posts from hours ago but not new ones. Pull-to-refresh spins forever. This is a background fetch failure. Confirm Background App Refresh is on for Herdr, then force-quit the app (swipe up from app switcher), reopen, and wait 10 seconds. If it persists, revoke the instance token (Step 4 above) — stale tokens cause silent 401 errors that the UI treats as empty timelines.

Push notifications worked in TestFlight but not in the App Store release. The App Store build uses a different APNs topic (bundle ID with production push certificate). Your instance’s push gateway (if self-hosted) or the upstream relay must be updated to use the new topic. The developer handles this for mastodon.social; other instances need admin action.

Does Herdr support multiple accounts on the same instance? Yes, but each account requires a separate OAuth token. Add accounts via Settings → Accounts → Add Account. Switching accounts reloads the timeline from scratch — this is by design to prevent cross-account data leakage in the local database.