> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/public-demo/docs_public-demo/troubleshooting.md).

# Troubleshooting

Use this guide when the public demo fails as a static artifact.

## Blank Page

Likely causes:

* CDN dependency failed to load.
* JavaScript runtime error during boot.
* Browser does not support import maps or required modern APIs.
* Service worker is serving an old cached shell.

Checks:

1. Open DevTools console.
2. Check failed network requests.
3. Hard refresh with cache disabled.
4. Unregister the service worker and reload.
5. Test in a fresh browser context.

## Splash Renders But Enter Does Nothing

Likely causes:

* An overlaying element is intercepting pointer events.
* React failed after initial render.
* A stale service worker is serving old CSS or HTML.

Checks:

1. Inspect the button with DevTools.
2. Verify the button receives pointer events.
3. Check console and page errors.
4. Clear site data and reload.

## Battlefield Is Blank

Likely causes:

* The battlefield container has zero width or height.
* The generated battlefield image or hero standees failed to load.
* A runtime error stopped React rendering.

Checks:

1. Inspect the 2D board dimensions.
2. Open `./assets/battlefield/background.webp` from the deployed URL.
3. Test desktop and mobile widths.
4. Check page errors.
5. Confirm the responsive layout gives the battlefield a minimum height.

## Images Missing

Likely causes:

* Asset paths are wrong under a path prefix.
* Files were not copied into the deployed artifact.
* The service worker precache list references missing files.

Checks:

1. Open `./assets/showcase/heroes-banner.jpg` from the deployed URL.
2. Open `./assets/battlefield/background.webp` and each `./assets/battlefield/heroes/*.webp` from the deployed URL.
3. Open each `./assets/portraits/*.jpg` from the deployed URL.
4. Check the service worker install step for `cache.addAll()` failures.
5. Verify the asset exists under `public-demo/assets/`.

## Background Music Missing Or Silent

Likely causes:

* Browser autoplay policy blocked audio before user interaction.
* The MP3 path is missing from `BACKGROUND_MUSIC_TRACKS` in `index.html`.
* The MP3 file was not uploaded under `public-demo/assets/music/`.
* A stale service worker is serving an older shell.

Checks:

1. Enter the demo with the splash button before expecting music to play.
2. Open `./assets/music/01_mythic_battle_theme_take_1.mp3` from the deployed URL and confirm it returns `200` with an audio content type.
3. Confirm the header music button changes between play and stop states.
4. Clear site data or unregister the service worker, then reload.
5. Check `localStorage["factionos-demo-background-music-v1"]` only for track index and current-time resume data; it is not a playlist manifest.

## First Load Fails Offline

This is expected. The first-ever visit must fetch `index.html` and CDN dependencies before a service worker can cache them.

Supported offline behavior starts after one successful online visit and service worker activation.

## Offline Reload Fails After Online Visit

Likely causes:

* Service worker did not register.
* Service worker scope is wrong.
* A precached file is missing.
* The cache version changed while testing.

Checks:

1. Confirm `navigator.serviceWorker.ready` resolves.
2. Confirm the scope matches the deployed demo path.
3. Inspect Cache Storage.
4. Check service worker install errors.
5. Reload online once, then retry offline.

## Works At Root But Not Under `/factionos/`

Likely causes:

* An absolute path such as `/sw.js` or `/assets/...`.
* Manifest start URL or scope is not relative.
* Service worker registered with a root scope.

Checks:

1. Search for root-relative paths in `index.html`, `sw.js`, and `manifest.webmanifest`.
2. Serve locally under `/factionos/`.
3. Confirm all same-origin requests include `/factionos/`.

## Stale UI After Changes

Likely causes:

* Service worker cache still controls the page.
* `CACHE_VERSION` was not bumped after shell asset changes.

Fix:

1. Bump `CACHE_VERSION` if the precache changed.
2. Unregister the local service worker.
3. Clear site data.
4. Reload and confirm the new `sw.js` installed.

## Wrangler Pages Deploy Fails With `/accounts//`

Likely causes:

* `CLOUDFLARE_ACCOUNT_ID` is unset.
* A sourced `.env` file defines `CLOUDFLARE_ACCOUNT_ID=` as a blank value.
* Wrangler is logged in but cannot infer the account for `pages deploy`.

Fix:

1. Confirm the target project exists:

   ```bash
   npx wrangler pages project list
   ```
2. Deploy with an explicit account id:

   ```bash
   CLOUDFLARE_ACCOUNT_ID=<account-id> npx wrangler pages deploy public-demo \
     --project-name=factionos-public-demo \
     --branch=main \
     --commit-hash="$(git rev-parse HEAD)" \
     --commit-message="$(git log -1 --pretty=%s)"
   ```

## GitHub Pages Workflow Fails

The GitHub Pages workflow is a fallback path, not the official production deployment. It fails when repository Pages is not enabled and configured for GitHub Actions. Use the Cloudflare Pages Wrangler deploy flow for production, or enable repository Pages before relying on `.github/workflows/pages.yml`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/public-demo/docs_public-demo/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.