dropbits Documentation

Troubleshooting

Lean checklist for install and deploy. Owner-facing Admin issues: see Site owners guides.

503 upgrade_required

Cause: pending migrations after a code ship without migrate.

Fix: on the install:

DROPBITS_SITE=<id> php bin/site migrate
DROPBITS_SITE=<id> php bin/site boot

Or re-run ./deploy <id> without --skip-migrate.

Login / default password refused

Live sites refuse the demo admin / admin password. Set DROPBITS_ADMIN_PASSWORD (or change the user) before flipping live. See Log in & roles.

Pack PHP missing / tools unknown

Pack files are present but the capability is not enabled. Brochure boot loads zero pack PHP until enable. Run ./bin/site enable <capability> or Admin → Site → Enable.

Deploy wiped content (or site.db missing after remote)

Content-owned remote deploy must restore site.db + uploads from .dropbits-deploy-swap/ after rotate. If verify fails with “site.db missing”:

  1. Do not purge the swap.
  2. Copy sites/<id>/data/{site.db,uploads,…} from the swap back into the live tree.
  3. bin/site boot.

Avoid ./deploy <id> --with-content unless you intentionally push a DB.

Theme newer-path prompt

With CONTENT_OWNED=1, deploy asks when the install has newer theme files (keep / pull / overwrite / abort). That is themes only — not DB/uploads.

Assistant / LLM “no key”

Server key paths and browser BYO: LLM key for operators and LLM chat & API key. CLI tool-run does not need a key.

Forgot password does nothing

Needs the mail pack enabled and configured (users.email, outbound mail). Kernel LogMailer is not a production reset fallback.

Wrong site / empty demo

Check DROPBITS_SITE (env / .htaccess SetEnv) and the install sites.json path for that id. Private ids belong in sites.local.json on the host, not tracked sites.json.

See also