> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opensubs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# When an alert opens

> Every alert kind, what it means, what fixes it, and the outages behind most of them.

OPENSUBS PLATFORM

Every alert lands on **Settings > Operational health**; Home's **Needs attention** banner counts the open ones. The watchdog checks every 15 minutes and resolves an alert by itself once its check passes again.

| Alert | What it usually means |
| - | - |
| **Job stalled** | A scheduled job hasn't finished on time. **Notification sender** stalled usually means the app is unreachable (outage 2); every daily job stalled at once suggests a paused database (outage 1). |
| **Job failed** | The job's latest run errored, and the alert carries the error text. Clears on the next clean run. |
| **Queue lagging** | Queued work (emails, imports, bulk runs, Shopify updates) is piling up faster than it drains. Usually the app is unreachable (outage 2). |
| **Notification deliveries failed** | Emails or texts gave up after their retries in the last 24 hours. Fixes: [When emails don't arrive](https://docs.opensubs.com/platform-v2/run/when-emails-dont-arrive.md) and [When texts don't arrive](https://docs.opensubs.com/platform-v2/run/when-texts-dont-arrive.md); the **Integration connections** panel quotes the provider's own errors (step 5). |
| **Store import failed** | The initial store sync stopped partway. Home shows the same failure with a **Retry import** button; the import resumes where it stopped. |
| **Bulk operation failed** | A bulk run gave up partway (finishing with a few failed rows never alerts). Open the run and read its results ([Change many at once](https://docs.opensubs.com/platform-v2/run/change-many-at-once.md)). |
| **Promo revert abandoned** | A promotion's temporary discount is stuck on a subscription: \~24 hours of retries couldn't take it off. The promotion's own page shows the same problem. |
| `shopify-jobs-failed` | A queued Shopify update gave up after its retries; this one shows its raw name. If the failed update was removing a one-time item, that item bills again next cycle. |

**1. Read it, then acknowledge it**

* Each alert names its kind and job, when first seen, when last confirmed, and a detail line of counts or error text.
* Click **Acknowledge**: the banner turns from yellow to blue and gains an **Acknowledged** badge.
* Acknowledging is bookkeeping, not a fix: the alert stays until its check passes.
* For a **Job failed**, find the job on the **Scheduled jobs** panel and click **Recent runs**: a failed run shows its error and what the job recorded, and **View all runs in Supabase** has the full history. A single failed run between clean ones already healed.

![Operational health: an open alert naming its kind and job, already acknowledged.](https://mintcdn.com/opensubs-docs/T6NpYT9MdOxqnOk5/images/platform-v2/run/19-open-alert.png?fit=max\&auto=format\&n=T6NpYT9MdOxqnOk5\&q=85\&s=ab4585ab57ebbf70b53466de3e926db4)

> [!TIP]
>
> **Checkpoint:** alert acknowledged and matched to its row in the table.

> [!NOTE]
>
> **The next three steps are three different outages.** Do the one that matches and skip the others.

**2. Outage 1: a paused Supabase project**

* Free-tier Supabase projects pause themselves, and everything scheduled stops with them, billing included. The symptom: **Job stalled** across the daily jobs.
* The fix: unpause the project in Supabase and watch the **Scheduled jobs** panel for runs landing again; keep your organization on Pro so it can't recur.
* Billing catches up on its own: the next hourly billing run after your **Daily billing time** sweeps everything that came due.

> [!NOTE]
>
> **Catch-up can't double-charge.** Each due cycle bills exactly once, even when catch-up lands more than one on the same day.

> [!TIP]
>
> **Checkpoint:** jobs green again.

**3. Outage 2: the app unreachable**

* When your Vercel deployment goes down, the portal goes dark and queued work backs up: **Job stalled** opens for **Notification sender** within 30 minutes, then **Queue lagging**.
* Billing is unaffected: it runs inside your database, not the app.
* The fix: check the latest deployment in your Vercel dashboard. Once the app answers, the queues drain themselves; no replay, no cleanup.

> [!TIP]
>
> **Checkpoint:** app back, queues empty.

**4. Outage 3: a 503 after an update**

* A 503 that says **Database schema out of date** means new code deployed before its database migrations ran.
* The fix is the migrate step of [Update the platform](https://docs.opensubs.com/platform-v2/run/update-the-platform.md): run `npm run merchant:migrate`, then reload the site.

> [!TIP]
>
> **Checkpoint:** the site answers again.

**5. Check the integration connections panel**

* **Integration connections** checks every connected provider live against its own servers: the same checks each card's **Test connection** button runs.
* **Healthy**: the saved credentials verified just now. **Failing**: the provider rejected them or never answered (after three tries); the row says which, and **View logs in** that provider opens its console. **Connected** just means there's no live check to run.
* Each row also counts the last 24 hours' failures in both directions (errored calls *from* the provider, rejected sends *to* it), with the latest messages quoted underneath.
* **Update available** just means a newer one-click setup shipped; the row links to **Integrations** to apply it. On the Shopify rows, **Current** is the aim, **Update available** resolves with a normal [platform update](https://docs.opensubs.com/platform-v2/run/update-the-platform.md), and **Unsupported** means update soon.
* Checks refresh in the background (the line under the panel says when), so give a fix a couple of minutes to show.

![Integration connections: the Shopify version rows, then each connected provider checked live against its own servers.](https://mintcdn.com/opensubs-docs/T6NpYT9MdOxqnOk5/images/platform-v2/run/36-integration-connections.png?fit=max\&auto=format\&n=T6NpYT9MdOxqnOk5\&q=85\&s=3ec1eec91438928da7fc9350559bf3f2)

> [!TIP]
>
> **Checkpoint:** every row **Healthy** or **Connected**, nothing **Failing**.

**6. Check the webhook delivery panel**

* **Webhook delivery (24h)** counts what Shopify told your platform, topic by topic; **Recent failures (7d)** lists the latest with their error text.
* The occasional failed row heals itself: Shopify retries failed deliveries on its own.
* Sustained failures across many topics are the real signal: check your Supabase project's Edge Function logs, then hand the error text to whoever runs your code.

![Webhook delivery over 24 hours, counted by topic.](https://mintcdn.com/opensubs-docs/T6NpYT9MdOxqnOk5/images/platform-v2/run/20-webhook-delivery.png?fit=max\&auto=format\&n=T6NpYT9MdOxqnOk5\&q=85\&s=a1dbe8080b9875831ad879fb12a9eeb2)

> [!TIP]
>
> **Checkpoint:** failed counts falling, not climbing.

> [!WARNING]
>
> **The stop rule.** A migration failing the same way twice, a 503 that won't clear even though `npm run merchant:migrate` reports `0 pending` ([Update the platform](https://docs.opensubs.com/platform-v2/run/update-the-platform.md)), or any advice that starts with "just edit the database": stop and hand it to whoever runs your code. Never hand-edit the database.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.