Troubleshooting
Almost everything that looks broken in Sunset Beach, NC is one of two things: your phone could not reach the backend, or the backend could not reach one of its upstream sources and is telling you so. The app never passes old data off as current — it labels it — so the fix is usually to read the label, check your connection, and pull to refresh. Nothing below needs an account, a login or a reinstall; the app has none of those.
If a symptom is not here, reach the support team with what screen you were on, what it said, what you expected and roughly when. If a number looked wrong, the Sources screen (Info › Where this comes from › Every upstream) and the ⓘ note beside that section say where it came from — mentioning that saves a lot of guessing.
The app won’t load
Section titled “The app won’t load”| What you see | What it means | What to do |
|---|---|---|
| A full screen reading “Can’t reach the beach”, a reason, and a Try again button | The app has no saved copy on this phone and its request to sunsetbeach.neuralconfig.com failed or timed out. Requests give up after 30 seconds and the whole attempt after 60. | Check you have signal, then tap Try again. Once one load has succeeded the app keeps a copy on disk and shows it on the next cold start instead of this screen. |
| The reason is “The server returned HTTP 5xx.” | The backend answered with an error. | Retry in a minute. https://sunsetbeach.neuralconfig.com/api/health shows whether the backend is up and which sources are struggling. |
| The reason begins “Couldn’t read the response: …” | The backend’s payload no longer matches what this build of the app expects. A saved copy that fails to decode is deleted, so this only appears on a fresh load. | Update the app from the App Store. |
| The web page says “Reading the instruments…” for a long time, or “Couldn’t reach the backend — …” | Same as the app: the page could not fetch /api/conditions. | Reload; the browser’s own error follows the dash. |
A banner sits at the top of every tab
Section titled “A banner sits at the top of every tab”| Banner | What it means | What to do |
|---|---|---|
| ”Showing the last data loaded — …” | A refresh failed after an earlier successful load. What follows the dash is the network error. Everything on screen is as old as the Updated … time. | Pull down on any tab to refresh. |
| ”Saved … — refreshing…” | The app drew the copy saved on disk while it waits for the network. It waits for connectivity rather than failing at once. | Give it up to a minute or check your signal. If the request then fails, this becomes the Showing the last data loaded banner. |
A card says Cached or Unavailable
Section titled “A card says Cached or Unavailable”Only a panel that is not live gets a badge, so a badge is information, not noise.
| Badge | What it means | What to do |
|---|---|---|
| Cached (clock icon) under a card, or on a row in Sources | That upstream could not be reached, and the backend is serving its last known good copy. The Sources row’s detail says when it was fetched and why it fell back. | Nothing on the phone will fix it — the fault is upstream. The reading is real, just older than usual. See How fresh the data is. |
| Unavailable (warning triangle) | That upstream failed and there is no fallback copy within its window, so the panel is missing or empty. | Wait for the source to come back. /api/health shows the error text for each source. |
| The Beach info tab’s Sources row reads N live · N cached · N down in orange or red | Some of the Info sections’ sources are cached or down. | Open Sources for the per-row reason. |
| ”None of this is loaded right now. Sources has the detail.” on the Beach info tab | Every source that feeds the Info tab is down at once. | Open Sources; almost always a connectivity problem on the phone. |
| A source’s status line ends “(dev mirror — data may lag)“ | Launch Library rate-limited the backend and it fell back to The Space Devs’ mirror. | Expected under load; launch times may be hours behind. |
A section is empty or missing
Section titled “A section is empty or missing”| What you see | What it means | What to do |
|---|---|---|
| ”No tide predictions available.” on Water | CO-OPS predictions could not be fetched and no cached copy exists. | Wait; predictions are cached for 6 hours once they load. |
| ”The forecast text couldn’t be read.” under Surf zone forecast | The NWS surf zone product could not be fetched or parsed. | Wait for the next issuance. The raw text is at /api/surfzone/raw. |
| ”No curve data in range.” on the tide chart | You are looking at a restored or stale payload whose four-day curve no longer covers now. | Pull to refresh. |
| ”No sunset model available.” / “No sunrise model available.” | Open-Meteo’s sky data is missing. | Wait; it refreshes every 15 minutes. |
| The Right whales section is not on the Nature tab | Out of season and no management area is in force — the section hides itself by design. | Not a fault. |
| Birds says “Not configured” / “An eBird API key is needed for this panel.” | The deployed backend has no eBird API key. eBird is the only source that needs one. | Nothing on the phone; the operator sets the key. |
| ”No sightings available.”, “No bird data available.”, “No migration radar available.”, “No turtle data available.”, “No marine life data available.” | That upstream failed with no cached copy. | Check the Sources screen. |
| The migration radar shows a sentence and no numbers | It is daytime — nocturnal migration readings are only valid after dark. | Check again after dark. |
| ”Season totals weren’t found on the page — the layout may have changed.” under Sea turtles | The Sunset Beach Turtle Watch page changed shape; the season model still shows. | Report it to support. |
| ”Pier page loaded but no concert entries were recognised — the layout may have changed.” on Events | The pier’s concert page was redesigned. | Report it to support. |
| ”Nothing scheduled in the next few weeks.” on Events | No calendar, concert or launch entries in the next 45 days. | Pull to refresh; check Sources. |
| ”Nothing matches those filters.” on Events | Every filter chip is deselected. | Tap All. |
| No Next visible launch card | No upcoming launch passes the visibility test — launches are still listed as rows. | Not a fault. See How the app judges things. |
| Fishing says “The pier is shut for the winter, so this is the last report of the season rather than yesterday’s.” | The newest pier report is more than ten days old. | Not a fault. |
| ”The pier’s daily report couldn’t be read, so nothing here is live — the seasons below are an almanac.” | The pier’s RSS feed was unreachable. | Wait; check Sources. |
| ”The list of proclamations in force couldn’t be read this time, so nothing here has been checked against it.” | The NC DMF proclamations page was unreachable. | Confirm limits against NC DMF before keeping a fish — always. |
| A “When to go” window reads in season rather than a score | That window kind is not scored, only timed. | Not a fault. See When to go. |
| Search shows “Nothing for ”…"" | No section title, synonym or explainer word starts with what you typed. | Try a shorter word. |
| The keyboard does not appear when search opens | Auto-focus needs iOS 18; on iOS 17 tap the field. | Tap the field. |
Alerts never fire, or never arrive
Section titled “Alerts never fire, or never arrive”The tide, moon and launch alerts are scheduled on the phone; the “When conditions change” alerts are pushed from the backend and are off by default. The Alerts sheet opens from the bell on Today, Water and Events, or from the Alerts row on the Info tab. Full detail is on Alerts and notifications.
| What you see | What it means | What to do |
|---|---|---|
| ”Notifications are turned off for this app in iOS Settings, so nothing here can fire.” / “Nothing queued — notifications are off for this app.” | You declined the permission prompt. iOS asks only once. | Tap Open iOS Settings → Notifications → Sunset Beach → Allow. |
| ”Nothing queued yet — tap Turn on notifications above and iOS will ask once.” | Toggles are on but permission has never been requested. | Tap Turn on notifications. |
| ”Nothing queued. The app needs to load conditions at least once before it can schedule anything.” | Permission is granted but the app has never loaded a payload. | Get online, let it load, reopen Alerts. |
| ”Nothing queued — every alert is switched off.” | Every toggle is off. | Turn one on. |
| The queue count falls to zero after a couple of weeks unopened | Local alerts are built from the last payload; tide predictions run about 15 days ahead. | Open the app — every load rebuilds the queue. |
| Send a test notification is greyed out | Permission is not granted. | Allow notifications first. |
| No pushed alerts although the “When conditions change” toggles are on | Three possibilities: registration with the push service failed (the app does not show this), nothing has changed since the first check (the first check after switching on records state and sends nothing), or conditions have simply stayed the same. | Toggle the alert off and on again to re-register, and remember these fire only on a change — rip risk rising to High, a new advisory, a new spill, a new NWS alert, a spectacular sunset or sunrise. |
| Tapping an NWS alert push opens the Alerts screen, not Today | That is where it points. | Not a fault. |
Widgets and the Live Activity
Section titled “Widgets and the Live Activity”| What you see | What it means | What to do |
|---|---|---|
| A widget reads “No data” with “HTTP 5xx” or “The request timed out.” | The widget’s own fetch of /api/summary failed. It retries in about 10 minutes. | Check connectivity; opening the app does not feed the widget — it fetches on its own schedule. |
| A widget shows a score of 88 and “Go. Best for surfing.” | That is the placeholder used in the widget gallery and before the first refresh. | Wait for the first refresh (up to 30 minutes). |
| A small clock icon beside the widget score | The summary was built from last-known-good data. | Nothing to do; see How fresh the data is. |
| The launch Live Activity never appears | Live Activities are disabled for the app, the app was not opened during the window (an hour before launch to 15 minutes after), or the launch is not visible from the beach. | Enable Live Activities in iOS Settings and open the app inside the window. See Widgets and the launch Live Activity. |
| The Live Activity reads “Scrubbed — no launch tonight.” or “Holding. …” | The backend pushed the provider’s new status. | Informational. |
Siri, Shortcuts and sharing
Section titled “Siri, Shortcuts and sharing”| What you see | What it means | What to do |
|---|---|---|
| A Siri phrase does nothing, or opens the Today tab | The phrase must include the app’s name; without it Siri has nothing to match. | Say the phrase as listed on Siri, Spotlight and Shortcuts. |
| A Shortcut’s screen parameter shows as broken after an app update | The section it pointed at no longer exists under that id. | Re-pick the screen in the Shortcut. |
| The share button is missing on Water or Events | Water has nothing to share without a next tide extreme; Events has nothing without a visible launch or a future event. | Expected. See Sharing conditions. |
| Shared text says As of an hour ago | The stamp is the payload’s own time, and the payload may be last-known-good. | Pull to refresh before sharing. |
Things that look wrong but aren’t
Section titled “Things that look wrong but aren’t”- Times look off while you are travelling. Every time in the app is the beach’s own (US Eastern), whatever time zone your phone is in.
- “Water” on Today and “Waterway temp” on Water differ by several degrees. One is the sea buoy, the other an Intracoastal Waterway gauge about 12 miles away. The swimmer’s number is Today’s.
- Water quality says “No advisory” but a spill line is showing. Spills are reported between the weekly water samples — that line exists precisely so a clean reading is not taken at face value.
- Beach cams don’t play inside the app. They open in Safari, and the town’s cam is a still image.
- There is no live ship position on a map. The app names what a ship probably is from published schedules and links to trackers; it has no vessel layer.
Next steps
Section titled “Next steps” How fresh the data is What Cached and last known good mean, and how old each source can be.
Alerts and notifications Local versus pushed alerts, their defaults, and the permission flow.
Limits and what it doesn't know The gaps that are by design, not faults.
Where every number comes from Every upstream and its known limits.