# Site Diagnostics

Every activated build includes a diagnostic layer that detects broken feature states on deployed sites. Instead of a blank page or a cryptic error, you get a styled error page, a console log with fix instructions, and an in-page overlay for partial failures.

## How does it work?

sitemd production builds generate three diagnostic mechanisms:

| Mechanism | When it fires | What it covers |
|---|---|---|
| `500.html` error page | Hosting platform returns HTTP 500 | Server-level failures, broken deploys, missing files |
| Inline diagnostic script | Page loads but auth/data features fail | Script 404s, license check failures, provider misconfiguration |
| Build-time warnings | During `sitemd build` | Missing auth.js or data.js when a provider is configured |

All three are automatic. No configuration needed.

## The 500 error page

Every production build writes a `500.html` file to the site root, alongside the existing `404.html`. Major hosting platforms serve this page when a server error occurs:

- **Cloudflare Pages** — serves `500.html` on 500 errors
- **Netlify** — serves `500.html` on 500 errors
- **Vercel** — serves `500.html` on 500 errors

The page uses your site's theme, brand name, and favicon. Visitors see a clean "This site is experiencing a temporary issue" message with a link back to the homepage.

### Console diagnostics

Open your browser's developer console on the 500 page to see fix instructions:

```text
[sitemd] Site Error Diagnostics
  Your site returned a 500 error.
  This typically means:
    1. Auth or data scripts were not properly included during the last build
    2. The build produced incomplete output
    3. The hosting platform encountered a configuration issue

  To fix:
    1. Rebuild:  sitemd build
    2. If build warns about modules:  sitemd auth login
    3. Redeploy: sitemd deploy
```

### Build metadata

The 500 page includes an HTML comment with build metadata. View source to see:

```html
<!-- sitemd-build: {"mode":"activated","built":"2026-03-27T...","pages":12} -->
```

This tells you the build mode and how many pages were generated — useful for diagnosing whether the build itself was the problem.

## Inline diagnostic overlay

When a page loads successfully (HTTP 200) but auth or data features fail, an inline diagnostic script detects the failure and shows a small overlay in the top-right corner of the page.

This covers failures that happen *after* the page renders:

| Failure | Detection method | Timing |
|---|---|---|
| auth.js or data.js returns 404 | Script `onerror` event | Immediate |
| License check fails | `sitemd:auth-failed` / `sitemd:data-failed` events | Within seconds |
| Script loads but never initializes | Timeout (8 seconds) | Delayed |
| Page content stuck hidden | DOM state check | At timeout |
| Gated sections permanently hidden | DOM state check | At timeout |

### What the overlay looks like

A small dark card appears in the top-right corner with the primary issue. Click the dismiss button to hide it for the current browser session.

The overlay also unhides page content if the [auth flash-prevention script](/docs/user-auth#how-it-works) had hidden `<main>` — showing broken content is better than showing nothing.

### Console messages

Each detected issue logs a specific fix to the browser console:

| Issue | Console message |
|---|---|
| Script 404 | `auth.js failed to load` — Fix: `sitemd auth login && sitemd build && sitemd deploy` |
| License failure | `Auth module license check failed` — Fix: `sitemd deploy` (re-verifies activation) |
| Init failure | `auth.js loaded but failed to initialize` — Fix: check provider settings in `settings/auth.md` |
| Hidden content | `Page content is hidden (auth flow incomplete)` — symptom of the above issues |

### Where it runs

The diagnostic script is injected into activated build pages that reference auth.js or data.js. It does not run:

- On localhost or 127.0.0.1 (the dev server has its own feedback)
- In [trial mode](/docs/build-modes#trial-mode) (trial has the dev banner instead)
- On pages without auth or data features configured

## Build-time warnings

When you run `sitemd build` with an auth or data provider configured but the corresponding runtime file is missing from the output, the build logs a warning:

```text
  ⚠ Auth is configured but auth.js is missing from the build output.
    Fix: Run "sitemd build" while connected to the internet to refresh modules.
```

This catches the problem before you deploy. The most common cause is building without a valid activation. Authenticate and activate your site, then rebuild.

## Common scenarios

### Deployed site shows a 500 error

The hosting platform can't serve the site. Open the 500 page's console for diagnostics, then:

1. Run `sitemd build` — check for warnings
2. If modules are missing: `sitemd auth login` to refresh credentials
3. Redeploy: `sitemd deploy`

### Page loads but is blank

The auth flash-prevention script hid content and auth.js never initialized. The diagnostic overlay will appear and unhide the page. Check the console for the specific failure (usually a license or provider issue).

### Gated content never appears

auth.js didn't complete initialization, so gated sections stay hidden. The overlay detects this after 8 seconds. Fix the underlying auth issue — usually redeploying via `sitemd deploy`.

### Build warns about missing files

The site's authentication has expired. Run `sitemd auth login` to re-authenticate, then `sitemd deploy` to rebuild and deploy.

## Related

- [System Pages](/docs/system-pages) — The 404, access denied, and maintenance pages
- [Build Modes](/docs/build-modes) — trial vs activated
- [Deploy](/docs/deploy) — The deploy flow and site activation
- [User Auth & Gating](/docs/user-auth) — Auth runtime and content gating
- [Dev Server](/docs/dev-server) — How the dev server works and what it renders