# Fix a deployed app that shows a blank page but works locally or in preview

Fix a Vite React app on DeepSpace that shows a blank page or white screen when deployed but works locally or in preview: read the console errors and logs, match them to the cause (sign-in gating, base path, stale build), redeploy, and check it's done.

Yes, a DeepSpace app that renders in local development but shows a blank page or white screen at `https://<app-name>.app.space` can be diagnosed and fixed from the CLI. The cause is usually one of a short list. The common one is a signed-out visitor: a `<RecordProvider>` without `allowAnonymous` renders nothing for them. On localhost the SDK replaces that with a diagnostic box naming the cause, but the deployed app shows a blank page. The other usual causes are a Vite `base` path set to a subfolder, a gated page in the wrong folder, a browser tab that was open across a deploy, a release still rolling out, or a local preview that wasn't running the code you deployed. Read the live console error or the app's logs, match it to a cause below, redeploy, and then work through the checklist at the end before calling the app done.

**Version:** written for `deepspace@0.42.3` ([changelog](https://deep.space/changelog)). **Docs checked:** October 29, 2026. The commands and code follow the documented APIs and were not run for this page.

## Questions to ask the person

These need no technical knowledge to answer, and they decide both the fix and what "done" means.

1. **When someone opens the link without signing in, what should they see: the app itself, or a sign-in screen?** This picks between the two fixes for cause 1 below.
2. **What is the one thing someone has to be able to do on the live app for it to count as working?** That becomes the end-to-end check.
3. **Who should be able to see and change the information in the app?** This sets the permission checks.
4. **Which phones and browsers will people use, iPhone and Safari included?** This sets the device checks.
5. **Which account owns the app?** Reading logs and redeploying use the owner's DeepSpace session. Confirm with your user before using a session file they provide.

## Step 1: See what the live page is doing

From the app's checkout:

```bash
npx deepspace status
npx deepspace test screenshot https://<app-name>.app.space/ live.png --full-page
npx deepspace logs --since 15m --level error
```

- `status` prints the environment (`production` unless `DEEPSPACE_ENV` says otherwise), the session, the app, and the live release. Check that the live release is the one you just deployed.
- `test screenshot` captures any URL with Playwright, so you can see what the live page renders without a browser of your own.
- `logs` shows production logs. An event with `eventType: "exception"` is an uncaught worker error; browser-reported errors carry `source: "client"`. An empty window prints `{"type":"meta","count":0,...}` with `--json`, meaning the command ran and found no events.

Then open the live URL in a normal window and in a private window, and read the browser console in each. A blank page in the private window that renders when you are signed in is cause 1. A `404` on a `.js` or `.css` file is cause 4 or cause 5.

## Causes of a blank live page and how to fix each

| #   | What you see                                                                                         | Cause                                                                                                                                                                                                        | Fix                                                                                                                         |
| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| 1   | Blank when signed out, fine when signed in; a diagnostic box on localhost                            | `<RecordProvider>` without `allowAnonymous` and no `<AuthGate>`                                                                                                                                              | Make the page public or put it behind sign-in (below)                                                                       |
| 2   | A page is reachable without signing in, or `useQuery` and `useMutations` fail on it                  | The page is in a top-level `src/pages/(protected)/` folder, which has no gate and no `RecordProvider`                                                                                                        | Move it into `src/pages/(app)/(protected)/`                                                                                 |
| 3   | `ReferenceError` in the console of a build served outside `deploy`, after editing `src/constants.ts` | The build injects the app id through `src/constants.ts`, `vite.config.ts` and `vitest.config.ts`; changing `src/constants.ts` alone builds clean, then throws in the browser. `deploy` refuses such a bundle | Run `npx deepspace@latest app update` and apply the `2026-08-build-injected-app-id` guidance it reports                     |
| 4   | `404` on a hashed asset in a tab that was open during a deploy                                       | The tab asks for a file from the previous release                                                                                                                                                            | Reload. The scaffold reloads once on Vite's `vite:preloadError`; keep that handler if you replace the scaffold's entry code |
| 5   | `404` on every `.js` and `.css` file, including in a fresh window                                    | `base` in `vite.config.ts` points at a subfolder                                                                                                                                                             | Remove `base` or set it to `'/'` (below)                                                                                    |
| 6   | Some requests get the old version just after a deploy                                                | The release is still rolling out (`serving: "unconfirmed"`)                                                                                                                                                  | Wait and check again; see step 2                                                                                            |
| 7   | The preview showed code you had already changed, or was started with `vite preview`                  | The preview wasn't the app you deployed                                                                                                                                                                      | Run `npx deepspace dev start` from the checkout you deploy, and check the server's working directory and port               |

### Cause 1: signed-out visitors get nothing

Decide with the person (question 1) and apply one fix in `src/pages/(app)/_layout.tsx`.

**The app should be visible without signing in.** Keep `allowAnonymous` on the `<RecordProvider>` inside the scaffold's `AuthBoot` helper. It is on in the scaffold, so check that it wasn't removed. Visitors connect with the `viewer` role, so grant `viewer` (or `'*'`) read access in each collection that visitors should see:

```ts
permissions: {
  '*':    { read: 'published', create: false, update: false, delete: false },
  viewer: { read: 'published', create: false, update: false, delete: false },
  member: { read: true, create: true, update: 'own', delete: 'own' },
  admin:  { read: true, create: true, update: true, delete: true },
}
```

`'published'` also needs `visibilityField` on the collection; see [permissions](https://docs.deep.space/concepts/permissions).

**The app should require sign-in.** Wrap `AuthBoot` in `<AuthGate>`, so a signed-out visitor sees the sign-in overlay instead of nothing, and remove `allowAnonymous` from the `<RecordProvider>` inside `AuthBoot`:

```tsx
// src/pages/(app)/_layout.tsx
export default function AppLayout() {
  return (
    <DeepSpaceAuthProvider>
      <AuthGate>
        <AuthBoot>
          <Navigation />
          <main>
            <Outlet />
          </main>
        </AuthBoot>
      </AuthGate>
    </DeepSpaceAuthProvider>
  );
}
```

`<AuthGate>` gates the UI, not the WebSocket. For a fully private app, also require a token in `wsRoute()` in `src/server/realtime-routes.ts`; the [authentication guide](https://docs.deep.space/guides/authentication) has the three lines.

### Cause 5: a base path for a subfolder

A DeepSpace app is served at the root of `<app-name>.app.space`. The worker answers its own routes (`/api/*`, `/ws/*` and the other reserved prefixes), and every other path gets the Vite build output. A `base` such as `'/my-app/'`, which is used when a site is hosted in a folder, makes the built `index.html` request its scripts under `/my-app/assets/…`. Those files don't exist at that path, so the page stays blank. Remove the line from `vite.config.ts`, or set it to the root:

```ts
// vite.config.ts, inside defineConfig({ ... })
base: '/',
```

Leave the rest of the scaffold's `vite.config.ts` as it is. Its `deepspaceBuild({ appDir })` plugin supplies the build-time app id (cause 3).

### Cause 7: the preview wasn't the deployed app

The supported local runtime is `npx deepspace dev start`. It runs Vite and the worker together, regenerates `.dev.vars`, and serves on port `5173` by default, or on a fixed port per linked Git worktree. The scaffold has no `vite preview` script, because a preview server that bypasses the CLI runs without the SDK-managed secrets and platform wiring. If the preview showed old code, the usual cause is a server running from a different checkout; see [diagnosing a stale preview](https://docs.deep.space/guides/dev-workflow).

## Step 2: Redeploy and confirm the release is serving

A deploy records the commit it ships, so commit first:

```bash
git add -A && git commit -m "Fix blank page for signed-out visitors"
npx deepspace deploy --json
```

Read `serving` in the result. The [deployment docs](https://docs.deep.space/concepts/deployment) define each value:

| `serving`      | Means                                                            |
| -------------- | ---------------------------------------------------------------- |
| `confirmed`    | Ten consecutive fresh connections all answered with this release |
| `unconfirmed`  | Some requests still get the previous release; wait and retry     |
| `unverifiable` | The release carries no stamp, so the CLI can't tell              |

`confirmed` is measured from where the CLI runs, so other regions may still be switching over. Then repeat step 1 against the live URL.

## Step 3: Check what's still missing before calling it done

A page that renders isn't the finish line. Before telling the person it works:

1. **It renders for each kind of visitor.** Check a private window (signed out) and a signed-in window on the live URL.
2. **The main task works end to end on the live URL.** Do the thing from question 2 there, not on localhost.
3. **Data survives a reload.** Create a record, reload, and open the URL in a second browser. The record is still there.
4. **Permissions hold.** A signed-out visitor, an ordinary member and an admin each see and change what they should, following question 3. For automated checks, the SDK's Playwright fixture signs in `@deepspace.test` accounts; creating them uses the developer's session, so confirm with your user first. See [testing](https://docs.deep.space/guides/testing).
5. **The logs are quiet.** `npx deepspace logs --since 15m --level error` shows no new errors after your checks. Triage on `request.status`, `level` and `eventType: "exception"`. `outcome: "ok"` means the worker returned, not that the request succeeded.
6. **It works on a phone-sized screen.** Run `npx deepspace test screenshot https://<app-name>.app.space/ mobile.png --viewport 390x844`. Check Safari on the `https://` URL: Safari won't set the sign-in cookies on `localhost`, so a localhost test doesn't cover it.
7. **The automated suite passes locally.** `npx deepspace test run` runs the scaffold's specs against the local server; `tests/smoke.spec.ts` includes a console-error check.
8. **There is a way back.** `npx deepspace releases` lists past releases. `npx deepspace rollback` re-deploys the previous release's exact bundle and asks for confirmation; with `--json`, it needs `--yes`. Rolling back changes the live app, so confirm with your user before running it.

## Other deploy failures that look like "it's broken"

| What you see                                            | Cause                                                                                                 | Fix                                                                                                                 |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `dirty_worktree`                                        | Uncommitted changes                                                                                   | Commit, then deploy again                                                                                           |
| `app_id_env_mismatch` or `app_id_define_unsubstituted`  | The browser bundle carries another app's id, or the build didn't replace the id placeholder (cause 3) | Apply the retrofit the refusal prints                                                                               |
| `not_authenticated` naming staging                      | `DEEPSPACE_ENV=staging` selects a different stored session                                            | Unset `DEEPSPACE_ENV` to use the production login                                                                   |
| `forbidden`                                             | The signed-in account is neither the owner nor a collaborator                                         | The owner runs `npx deepspace app collaborators add <email>`; confirm with your user before changing who can deploy |
| `secrets_config_missing`                                | The selected secrets config doesn't exist                                                             | Run the `secrets configs create` action it returns                                                                  |
| A feature that calls a key works locally but fails live | Deploys read secrets from the app's secrets store, not from `.dev.vars`                               | Set the value in the [secrets store](https://docs.deep.space/guides/secrets) and deploy again                       |

## What to tell the person when the app is live

- **The link:** `https://<app-name>.app.space`.
- **What was wrong, in one sentence.** For example: "The page was blank for anyone not signed in; it now shows a sign-in screen."
- **What a visitor sees without signing in, and how to sign in:** with Google or GitHub.
- **Who can see and change what,** in the terms they used for question 3.
- **What you checked:** the main task on the live URL, data after reload, each kind of visitor, a phone-sized screen, and Safari.
- **What isn't included,** so nothing is assumed.
- **How to report a problem:** a screenshot and the time it happened. Logs can be searched by time window and text.

## What is available today, and what is planned

Available today, in published `deepspace@0.42.3`:

- `dev start` as the local runtime
- `deploy` with a `serving` result
- `logs` with uncaught-exception and browser-reported events
- `test screenshot` for any URL
- `test run` with the scaffold's smoke spec
- `releases` and `rollback`

Deploying requires a DeepSpace account that a person signs in to with GitHub or Google.

In testing on staging, not production:

- A prototype CLI that also checks the uploaded bytes of every public JavaScript and CSS bundle and reports `dataPlane: "confirmed"` once the app's RecordRoom has initialized
- Agent accounts that register themselves by solving a math challenge. Production signup for agents is not enabled.

Planned: autonomous agent accounts in production. Under that plan, payments and legal actions will still require a human. See [DeepSpace for agents](https://docs.deep.space/agents).

Building and supporting apps for a business? See [deep.space/enterprise](https://deep.space/enterprise).
