build/serve/check/etc. look for docs/ (falling back to src/) relative to the current directory, or to --projectRoot=<path> if you passed one. Either run the command from inside your project's root folder, or pass --projectRoot:

bxSites build --projectRoot=/path/to/my-docs

Run bxSites doctor to see the exact key/line the config loader rejected. Common causes: mixing tabs and spaces in YAML indentation, a stray trailing comma in JSON, or a key that expects an array (like nav or i18n.locales) written as a bare string. See Configuration for the full key reference.

build, serve, and search-index all need these four BoxLang modules. Installing bx-sites itself installs them automatically as box.json dependencies (install-bx-module bx-sites or box install bx-sites) - if you're seeing this, either the install didn't finish, or the module was registered by hand without its dependencies. Re-running box install from your project root re-resolves everything; bxSites doctor confirms which module (if any) is still missing.

A custom theme/ folder must provide both layout.bxm and page.bxm - doctor reports which one is missing. See Themes for the full contract, or run bxSites theme:new to eject a working built-in theme as a starting point instead of writing one from scratch.

serve watches docs/, your bxsites.yaml/.json, and a project-level theme/ override - a change anywhere else (for example editing a file under resources/ in a module checkout, not a real project) won't trigger a rebuild. If a change genuinely isn't reflected, stop serve, run bxSites clean to clear any stale build cache, then bxSites serve again.

build doesn't delete previously built output that no longer has a matching source page. Run bxSites clean before build to remove site/ and any build cache entirely, then rebuild from scratch. If a CI step reports success but the deployed site doesn't reflect it, check the actual build-step log output for Error: - a crashed build can still exit with a misleading status in some CI setups.

That's expected, not a bug: a locale doesn't need every page translated before it's usable. A page missing from docs/i18n/<code>/ still builds at its expected URL, showing the default locale's content with a small notice at the top. See Internationalization (i18n).

i18n:status checks per-locale page presence only, not per-page content parity - a locale copy can exist but still be missing a section added later to the default-locale page. Diff the locale file against its default-locale counterpart directly if you suspect this.