Skip to main content
Documentation

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.

On this page

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). 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:

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:

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.

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:

// 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 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:

// 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.

Step 2: Redeploy and confirm the release is serving#

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

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 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.
  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 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.

Building and supporting apps for a business? See deep.space/enterprise.