Last updated June 23, 2026

Troubleshooting

3 minutes read

Build fails with “broken link” errors

Symptom: bun run folio:build exits with DEAD [internal] /some/path.

The link validator runs before every build and fails on any internal link that doesn’t resolve to an existing page. To fix:

Check the path reported in the error output
Either fix the link to point to a page that exists, or create the missing page
folio.md skips mailto: links. It checks pure fragment links against headings on the current page.

The link checker runs automatically as part of bun run folio:build, npm run folio:build, or yarn folio:build.

Build shows `ALIAS` warnings

Symptom: the link validator prints ALIAS [internal] /old-path → /new-path.

A page with alias: in its frontmatter is a redirect stub. folio.md never renders it as a real page. Linking to an alias page instead of its destination is an antipattern. Update those links to point to the destination directly.

”Last updated” date isn’t showing

Symptom: the “Last updated” line is absent even though you’ve committed the files.

folio.md reads this date from git log at build time. Common causes:

Shallow clone in CI: most CI providers do a shallow clone by default with --depth=1. Pass fetch-depth: 0 to get the full history:
yaml
```
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
```
File not yet committed: git history doesn’t include newly created files. Commit the file first.
Running outside a git repository: folio.md silently skips git dates when git is unavailable. folio.md shows no error in this case. Verify with git log --oneline -5.

`folio dev` / `folio build` says “no folio.config.ts found”

Symptom: running folio dev or folio build prints folio: no folio.config.ts found in ….

The folio command-line tool looks for folio.config.ts in the current working directory. Make sure you’re running the command from your project root, not from inside node_modules or a subdirectory.

If you haven’t created a configuration file yet, run:

bash

bunx folio init

`folio.config.ts` throws a validation error

Symptom: the dev server or build exits with Invalid folio.config.ts:.

The error message lists every failing field and the reason. Common mistakes:

Error	Fix
`name: String must contain at least 1 character(s)`	`name` can’t be empty
`siteUrl: Required`	`siteUrl` requires a value. Add it to your configuration, for example `siteUrl: "https://docs.example.com"`
`siteUrl: Invalid url`	`siteUrl` must be a full URL with a scheme, for example `https://docs.example.com`
`icon: Invalid enum value`	The icon name isn’t in the supported list: see Icon Reference

Static assets return 404

Symptom: files placed in public/ aren’t served.

The public/ directory must sit next to folio.config.ts at your repository root. The build ignores assets placed elsewhere.

The site title shows in the wrong locale format

Symptom: the “Last updated” date uses the wrong format or language.

Set lang and seo.locale in folio.config.ts to match your target locale:

export default {
  lang: "fr",
  seo: { locale: "fr_FR" },
  // …
};

lang sets the <html lang> attribute. folio.md passes seo.locale to toLocaleDateString for the “Last updated” date and to the og:locale meta tag.