Troubleshooting

Troubleshooting

Failure modes that follow from how this repository is actually wired, and what to do about each.

The deploy workflow ran but the job was skipped

You started it with workflow_dispatch from a branch other than main. The job is gated on if: github.ref == 'refs/heads/main', deliberately, so a manual run from any other ref cannot reach the production Cloudflare secrets. Merge to main and let the push trigger it.

npm ci fails in CI but npm install works locally

npm ci installs strictly from package-lock.json and errors if the lockfile does not agree with package.json. If you changed a dependency, run npm install locally and commit the updated lockfile alongside package.json.

The deploy step fails on a fork

CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are repository secrets and are not available to forks. Build locally instead; publishing happens from the upstream repository.

A Tailwind class has no effect

tailwind.config.mjs only scans ./src/**. Two causes:

• The class was written in a file outside src/, such as anything in public/. Move the markup into a component or page.
• The class name was assembled at runtime from a variable, so the scanner never saw the literal string. Write full class names out and select between them with class:list, the pattern the rest of the site uses.

A custom color is not recognized

Only brand, accent, and chart are added to the theme. chart has named keys — chart-blue, chart-gold and so on — not numeric steps, so chart-500 does not exist. The data-viz components in src/components/dataviz/ set SVG attributes with hex literals rather than classes; changing the config alone will not move them.

The nav does not highlight my new page

The active-link test compares Astro.url.pathname, trailing slashes stripped, against each leftNav entry's href for exact equality. A nested route such as /features/detail will not highlight /features. Either add the route to leftNav or change the comparison to a prefix test.

The architecture diagram does not render

Mermaid.astro imports Mermaid from the jsDelivr CDN inside an inline module script and renders in the browser. So:

• Offline, or behind a network that blocks jsDelivr, no diagram appears. The build still succeeds, because nothing is rendered at build time.
• A Mermaid syntax error in the archDiagram string shows up only in the browser console, never as a build failure. Check the console after editing.
• The component guards on window.__rmMermaidInit so the library initializes once per page. If you add a second diagram, it is rendered by the same mermaid.run() call and does not need its own loader.

The /docs panel is blank

Three possibilities, in the order worth checking:

1. public/openapi.json is missing or is not valid OpenAPI. The page fetches it from the site root at runtime; check the network tab.
2. The Stoplight Elements script or stylesheet was blocked. They are loaded from jsDelivr with Subresource Integrity hashes — if the pinned version was changed without recomputing the integrity values, the browser blocks the resource and reports an integrity mismatch in the console.
3. The CDN is unreachable. There is no bundled fallback.

/docs is missing an endpoint the API serves

public/openapi.json is regenerated once a day, at 05:23 UTC, from the reportmate-api main branch. Run the openapi-sync workflow on main from the Actions tab to pick a change up immediately. If the workflow ran but nothing was committed, the exported spec was identical; the endpoint is not on the API's main yet.

The docs page renders light on a dark system theme

The inline script on /docs rewrites localStorage key mosaic-theme to {"mode":"system"} on every load whenever the stored mode is anything else, so a theme picked inside the Stoplight UI does not survive a reload. If the panel still renders light, the browser is refusing localStorage (a private window or blocked site data): the write fails silently and Stoplight falls back to its light default, while the page chrome still follows the system theme.

Canonical or Open Graph URLs point at reportmate.app on a local server

That is expected. Layout.astro builds the canonical link and the Open Graph image URL with new URL(..., Astro.site), and site in astro.config.mjs is https://reportmate.app, so every build and the dev server emit absolute https://reportmate.app/... URLs. A fork published under another domain must change site.

An image 404s in production but not locally

Assets must live in public/ and be referenced by root-relative path — /foo.webp, not ./foo.webp or ../public/foo.webp. Astro copies public/ to the site root verbatim; a relative path that happens to resolve in dev may not after the build.

Something looks wrong only in the built output

dist/ and .astro/ are gitignored but not cleaned automatically. If a build looks stale, remove both and rebuild:

rm -rf dist .astro

npm run build