Support

Direct help for common BaseBuddy setup, access, mapping, editing, and deployment tasks.

Support/How to fix failed setup checks

How to fix failed setup checks

Use BaseBuddy diagnostics to find the first failing config, owner, auth, content database, or storage check.

Use this when BaseBuddy setup shows a failed check, redirects you back to onboarding, or cannot reach Projects after installation.

Setup checks validate the selected BaseBuddy app-data backend, required env values, and the content database connection. They never look for setup scripts in your content schema.

Open browser diagnostics first

If BaseBuddy can render in the browser, open:

texthttp://localhost:8080/onboarding?diagnostics=1

The diagnostics view shows the same sections the setup flow uses:

SectionWhat it checks
App dataThe selected app-data backend exists, is readable, is writable, and validates
Owner accountAt least one local owner user exists
Environment valuesBASEBUDDY_AUTH_SECRET is present for local sessions
Database connectionBASEBUDDY_CONTENT_DATABASE_URL is present and reachable when checks run with database verification
Supabase storageOptional Supabase Storage env values are complete when any are set
S3-compatible storageOptional shared media storage env values are present when configured

Fix the first failed section, then rerun the check. Later sections can fail because an earlier config value is missing.

Use the CLI when the app cannot render

From the BaseBuddy repo root, run:

shpnpm basebuddy doctor

You can also run:

shpnpm setup:check

Use pnpm basebuddy doctor --skip-db-check when you only want to validate app data and not test the content database connection.

If app data is missing

Create it from the browser setup flow or CLI:

shpnpm basebuddy setup \
  --owner-email "owner@example.com" \
  --owner-name "Owner" \
  --owner-password "choose-a-strong-password"

For the default backend, the file must be named exactly:

textbasebuddy-data/basebuddy.config.json

It must live in basebuddy-data/ where BaseBuddy runs.

For Supabase/Postgres app data, confirm BASEBUDDY_APP_STATE_BACKEND is set correctly. Split-project app data also needs BASEBUDDY_APP_STATE_DATABASE_URL.

If owner or local auth fails

The setup flow creates the first local user. Set BASEBUDDY_AUTH_SECRET in env before completing setup. If the owner is missing, rerun setup with owner details or use:

shpnpm basebuddy user:create \
  --email "owner@example.com" \
  --name "Owner" \
  --password "choose-a-strong-password"

BaseBuddy uses local password sessions stored in app data. It does not require Supabase-hosted authentication for app sign-in.

If the content database check fails

Check BASEBUDDY_CONTENT_DATABASE_URL in env:

  1. It should start with postgresql:// or postgres://.
  2. It should include the right user, password, host, port, and database name.
  3. The machine running BaseBuddy must be able to reach that host.
  4. The database user must be able to inspect and write the mapped schemas you want to edit.

If your host cannot reach a direct Supabase connection, use the Supabase pooler connection string instead.

If optional storage fails

Supabase storage is only needed for images and files. If you set any Supabase storage value, set all three env values:

textBASEBUDDY_SUPABASE_URL
BASEBUDDY_SUPABASE_PUBLISHABLE_KEY
BASEBUDDY_SUPABASE_SECRET_KEY

If you are not using Supabase Storage for images or files, remove all three from env.

Verify the install

After setup reports ready:

  1. Sign in with the owner account.
  2. Create or open a project.
  3. Save mapping.
  4. Reload the app and confirm the mapping persists.
  5. Edit one mapped content field and save.

BaseBuddy should only update dirty mapped fields on normal save. Publish, unpublish, and archive remain explicit actions.