Troubleshooting

Most of what looks like a bug in 8-BitQuest is a guard doing its job. This page collects the failure modes the theme produces deliberately, the browser behaviours that are expected rather than broken, and the handful of genuine gotchas the codebase documents in place.

Failures on purpose

The build throws about SITE_URL. A production deploy is still on the https://example.com placeholder. This is intentional — it makes it impossible to ship canonical URLs and a sitemap pointing at the placeholder. Set SITE_URL in your host’s environment variables. On a host that is neither Netlify nor Vercel, also set DEPLOY_ENV=production so the gate can see it. Local builds and deploy previews are unaffected. See Deployment.

The contact form says “not configured yet”. That is the expected message when RESEND_API_KEY or CONTACT_TO_EMAIL is unset. The check is at request time, so a missing key never breaks your build — the form just reports its state. See Contact Form.

A content entry fails the build. Bad frontmatter is caught by the Zod schema with the entry named — an unparseable pubDate, a missing heroImage, an authors list that references a non-existent author, a project status outside the enum. That is the feature; fix the named field. See Content Collections.

A config value throws. The config layer is typed, so pnpm check and pnpm build catch a wrong shape. This is code you wrote, not external data, so it fails at build rather than shipping an empty string.

pnpm test fails with no checks found. The runner treats zero discovered *.test.ts files as a failure, on purpose, so the check suite can never quietly disappear. If you see this, you have moved or deleted the tests, not hit a runner bug.

Looks like a bug, but isn’t

A <Reveal> animation fires on page load instead of on scroll. You are almost certainly in Firefox, which does not yet support native scroll timelines. The theme ships no JavaScript fallback by design — the content still ends visible, it just plays once on load. This is the documented ceiling of the zero-JS <Reveal>. See Motion.

A parallax or zoom animation is frozen. Its clip frame is using overflow-hidden instead of overflow-clip. A hidden box is itself a scroll container, so the scroll timeline resolves to that frame — which never scrolls — instead of the page. Switch it to overflow-clip.

Mail sends without error but never arrives. You are still on the default [email protected] sender, which can only deliver to the address that owns your Resend account. Verify a domain in Resend and set CONTACT_FROM_EMAIL to an address on it.

Light mode looks blue, not white. That is the design. Light mode is a cool inversion of the dark navy — a light retro-blue desktop with white panels — not a cream or stark-white “paper” theme. See Colors.

Corners are square and shadows are hard-edged. Also the design. --radius is 0 and the pixel shadow has zero blur — the retro signature. Raise --radius and soften --shadow-pixel if you want a gentler look.

Genuine gotchas the code guards against

A modal <dialog> lands top-left instead of centred. Tailwind v4’s Preflight resets margin: 0 on every element, which wipes the user-agent dialog { margin: auto } that centres a modal. ui/_overlay.css restores margin: auto on [data-slot="dialog"] — so this only bites if you add a new dialog without the data-slot="dialog" tag the contract requires. Tag it.

A single-select behaves as multi-select. Astro emits a boolean attribute for false, not just true, and browsers treat any multiple attribute as present. The AdvancedSelect primitive guards this by passing multiple || undefined so Astro omits the attribute entirely. If you write a similar hidden <select>, remember: boolean attributes are omitted for undefined, not for false.

When something is genuinely wrong

Two dev-server quirks account for most “it should work” moments, and both are Astro’s content/CSS caching rather than your code:

• A renamed content entry keeps 404ing. Astro’s content layer caches entries; moving or renaming a folder while pnpm dev runs can leave the old entry cached and the new one missing. Restart the dev server — touching the file will not clear it.
• A utility class has no effect. In a long-running dev server, classes used only in newly created files can be missing from the generated stylesheet. Restart the dev server before hunting for a bug in your markup.

Images ship unprocessed on some hosts. sharp (Astro’s optional image dependency) has no prebuilt binary for your platform. pnpm add sharp installs it directly. See Images & Assets.

Node errors on install or test. The floor is 22.13.0, enforced by engines.node. Older releases fail on the test runner’s --experimental-strip-types even if the install itself appears to succeed.

When none of the above fits, pnpm build is the honest check — it validates content, config and references in one pass, and its error names the file and the value. The theme’s wiki/ documents each subsystem in depth if you need to go deeper than these docs.