How to fix BaseBuddy setup check errors
Open setup diagnostics, repair BaseBuddy app data, and rerun checks safely.
Use this when BaseBuddy shows:
textBaseBuddy setup needs attention. Open setup and run the checks.This means BaseBuddy stopped before opening the normal app because app data is missing, invalid, incomplete, or cannot be written.
Open diagnostics
Open:
texthttp://localhost:8080/onboarding?diagnostics=1For production, replace the origin with your deployed BaseBuddy URL.
If the browser will not render, run:
shpnpm basebuddy doctorFix the first failed section
| Failed area | What it usually means | What to do |
|---|---|---|
| App data | The selected backend is missing, malformed, unreadable, or not writable | Run setup again or fix file/database permissions |
| Owner account | No local user exists | Create the owner from onboarding or pnpm basebuddy user:create |
| Environment values | BASEBUDDY_AUTH_SECRET is missing | Set the env value and restart |
| Database connection | BASEBUDDY_CONTENT_DATABASE_URL is missing or unreachable | Recopy the database URL into env, restart, and rerun checks |
| Storage | Optional storage credentials are incomplete | Complete the set or remove it |
Do not apply setup scripts to your content schema. BaseBuddy app data belongs in basebuddy-data/ by default or in BaseBuddy-owned basebuddy schema tables when that backend is selected.
Recreate setup from CLI
If you want to recreate the initial setup from the command line:
shpnpm basebuddy setup \
--owner-email "owner@example.com" \
--owner-name "Owner" \
--owner-password "choose-a-strong-password"Then verify:
shpnpm basebuddy doctorConfirm normal app behavior
After the message is gone, sign in, open Projects, save a mapping, reload, and confirm the mapping persists. That proves BaseBuddy can read and update app data.