Troubleshooting

When something misbehaves on the course, you don’t want a manual — you want the one-line fix. Here’s the short list, ordered by what we see most.

I can’t sign in

Settings → confirm the API base URL is https://heycaddy-server-production.up.railway.app. If it was changed for testing, tap Apply to reset.
Sign out → sign back in. Tokens expire after 30 days; re-auth refreshes.
If signup fails with “email already in use” — sign in with that email instead. The signup endpoint is bcrypt + token; we don’t share auth state with other tools.

GPS shows “—” for yardage

iOS Settings → Hey Caddy → Location → set to While Using App.
If the course wasn’t enriched with GPS coords, the Glance YOUR SHOT card falls back to tee yardage. Tap any hole on Scorecard → if no green/tee coords show, the course needs the enrichment step (we run this server-side; ping support if a course is missing).
Cellular dead-zones: GPS itself doesn’t need cellular, but the initial “where am I” lock can take 10–20s outdoors after first launch. Move to open sky.

Voice didn’t hear me

Mic permission: iOS Settings → Hey Caddy → Microphone → on. Same for Speech Recognition.
If hands-free is misfiring on background noise (cart engine, wind, conversation), tap the bar at the bottom of Glance to stop the listener. Switch to Tap to talk for the rest of the round.
AirPods: confirm you’re paired and the iPhone is the active output. Apple’s “Hey Siri” can hijack the wake word — disable Siri during play if you keep colliding.

The score didn’t save

Pull-to-refresh on Scorecard. If the score still isn’t there, the request likely failed mid-flight. Re-enter via the score-edit sheet.
Multi-device foursomes: each device follows its own player’s scores. If you scored for someone else from your device, their device may not show it for ~10s (sync polls every 10s). After that, hit refresh on theirs.
Rare 400 race when 4 players post the same hole within ~50ms — known issue, retry the one that didn’t land. Fix is in flight.

Glance isn’t advancing to the next hole

Voice scoring: Glance auto-advances when your player has a score on the current hole. If you scored for someone else, manually swipe / tap the next hole on Scorecard.
If the bot says “hole 7” but Glance still shows hole 6, your phone’s currentHole is stale. Pull-to-refresh.

Bets card looks wrong

Tap the bet card → hole-by-hole grid → walk through it hole by hole. Most disputes are because someone’s score was logged wrong; fix the score and the bet re-settles.
If a press shows up twice — the auto-press fired AND someone manually pressed. Both are tracked separately by design. The combined ledger nets them out correctly.
If a Calcutta lookup shows a UUID instead of a name, the owner string didn’t match a roundPlayer. That’s expected for non-player owners; the name renders as-is.

Conditions card says “unavailable”

The conditions feed pulls from NWS via the heycaddy server. NWS occasionally returns slow on weekends — usually self-resolves within a minute. The card stays “unavailable” rather than blocking the round.
NWS coverage: continental US only today. International courses won’t populate conditions until we wire a global provider.

Kill switch

If something is really off — wrong scores, wrong bet config, etc — open the round on Scorecard and use the top-bar End button. The round is marked ended; you can start a fresh one. The old round stays in your history but settles as-is.

Still stuck

Email [email protected] with: your iPhone build version (Settings → bottom of the screen), the round ID (Scorecard top header → tap the title), and a screenshot. Most issues we can debug from those three pieces.