Troubleshooting

Resolve common content, configuration, asset, and development problems.

Start with the first diagnostic and follow its file and field path to the authored input. Run commands from the consumer root containing brandtree.config.ts.

Common fixes

Symptom	What to check
Preview reports no build	Run `brandtree build` from the consumer root. Keep both the generated `.brandtree/astro.config.mjs` and nonempty `dist/`; preview does not rebuild them.
A page is missing	Check draft flags, underscores/partials, locale filenames, malformed frontmatter, duplicate normalized routes, and dropped-page diagnostics. Run strict checking.
Config rejects an unfamiliar field	Use the configuration reference. Schemas reject unknown keys; an ADR may describe a future API.
A component fails reading `brand` or `ui`	Built-ins receive shared props automatically in Brandtree content MDX. Check explicit overrides for incomplete values. In custom Astro templates, pass the required props yourself.
Metadata is ignored	Export valid folder metadata or a factory returning it; see navigation.
A local asset is missing	Check filename case, project-root config paths, public URLs versus imported files, and diagnostic paths.
Remote fonts time out	Check build network access or register readable, licensed local fonts; verify the actual emitted font files.
Arabic characters disappear in social cards	Use a working Arabic-capable font. Inter fallback does not cover Arabic.
Types miss an author file	Inspect your own tsconfig’s include/exclude rules; it replaces the generated check project.
An installed version lacks a documented feature	Check `pnpm brandtree --version`. Update the project dependency and lockfile when upgrading, then regenerate the site.
Changes in generated files disappear	Move the fix into config, MDX, or your imported component. `.brandtree/` is recreated.

Some diagnostics retain a BLUME_ prefix from shared implementation history; use the accompanying file, field path, and message to locate the problem.

For a clean regeneration, first stop dev, remove only the disposable .brandtree/ directory, and rerun the command. Keep authored inputs intact. Ignore .brandtree/, .brandtree-verify/, and dist/ in version control.