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 php playground/bin/deploy <id> (or host-local ./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 sites/<id>/data/ from .dropbits-deploy-swap/ after rotate. Restore is not atomic (delete then copy while the site may still be live); PHP may keep writing the swap site.db until workers recycle. If verify fails with “site.db missing”:

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

Avoid ./deploy <id> --with-content (host-local) 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.

Mobile header flashes desktop nav, then hamburger

Guest compact layout is html.db-nav-compact, set before first paint by a blocking head script (id="db-nav-compact-sniffer") whenever nav-dropdown.css is on the page. nested-nav.js is defer and only owns clicks / resize.

If the header still snaps after a kernel ship:

  1. Hard-refresh (cached HTML from before the sniffer).
  2. Confirm guest HTML contains id="db-nav-compact-sniffer" after the theme CSS and nav-dropdown.css links.
  3. Theme hamburger rules must use html.db-nav-compact scoped to the shell header — not an unscoped .main-nav { display:none } and not a @media px that disagrees with --nav-mobile-max.

If the header is already compact and the whole viewport still blinks white between in-site clicks, that is MPA document paint. Optional: CSS View Transitions (@view-transition { navigation: auto; } plus a short fade) in dropbits-site.css or via patch_user_css. Do not add a fragment router / swap-main script for this.

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