Matrix App Debugging

When to Use

Use this when a Matrix app shows an error, blank screen, needs_build, missing icons, CORS failures, or console errors.

First Checks

cd ~/apps/<slug>
test -f matrix.json
test -f package.json
test -f dist/index.html

If dist/index.html is missing, build the app:

pnpm install --prefer-offline
pnpm build
test -f dist/index.html

needs_build

{"error":"needs_build","status":"needs_build"} means the gateway found a Vite app manifest but no usable build output.

Fix:

1. Check matrix.json has runtime: "vite" and build.output: "dist".
2. Run pnpm install --prefer-offline.
3. Run pnpm build.
4. Verify dist/index.html.
5. Reload the app window.

Manifest Checks

Good baseline:

{
  "name": "Whiteboard",
  "slug": "whiteboard",
  "description": "Collaborative drawing and notes",
  "version": "1.0.0",
  "runtime": "vite",
  "runtimeVersion": "^1.0.0",
  "listingTrust": "first_party",
  "category": "productivity",
  "icon": "whiteboard",
  "build": {
    "command": "pnpm build",
    "output": "dist"
  }
}

Avoid stale fields from old app formats such as type: "html-app" or type: "react-app" unless the current gateway explicitly supports them.

Console Error Triage

• needs_build: build output is missing.
• 404 /icons/<slug>.png: default icon asset missing or manifest points at a non-existent icon.
• 404 app bundle: entry or Vite base is wrong.
• CORS from provider API: app is calling a provider directly. Use Matrix integration routes.
• SecurityError from localStorage: app code is running inside the Matrix sandbox. Persist through window.MatrixOS.db; keep localStorage fallback code test-only/no-op.
• Missing or undefined saved fields: check matrix.json storage.tables declares the column and type.
• 401 /api/auth/ws-token: user is not authenticated or the route is being called from the wrong shell context.
• Clerk failed to load clerk.example.com: stale environment or image build used placeholder Clerk config.

Icon Fixes

• Use committed default icon assets for built-in apps.
• Manifest icon should be a slug, not an arbitrary URL.
• Verify the resolved icon path exists in Matrix's system icons.
• For games, prefer the shipped game-center asset unless the app has its own committed icon.
• Do not rely on runtime image generation for default icons.

Data Bridge Checks

• Confirm window.MatrixOS?.db exists before debugging state as an app bug.
• Check the manifest declares every table and persisted column used by the app.
• Reproduce create/update/delete failures and verify the UI rolls optimistic state back after bridge errors.
• For ordered lists, best scores, timers, histories, and stats, look for racing writes. Serialize dependent updates or use a single bridge operation when possible.
• Avoid treating a test-only localStorage guard as production persistence. The shell sandbox should use the bridge path.

Integration Errors

Customer VPSes should proxy integration requests to platform. If /api/integrations returns 404:

1. Check gateway env has internal platform URL/token.
2. Check platform has Pipedream credentials.
3. Do not copy Pipedream secrets into the customer VPS as a workaround.

Verification

Before saying fixed:

cd ~/apps/<slug>
pnpm build
test -f dist/index.html

Then reload the app and confirm:

• The app renders.
• Browser console has no app errors.
• Network tab has no bundle 404s.
• Any integration calls go through Matrix routes.