Build Errors

Page is missing param in generateStaticParams()

Full error:

Error: Page "/(docs)/[...slug]/page" is missing param "/[...slug]"
in "generateStaticParams()", which is required with "output: export" config.

Cause: A page is reachable (via a sidebar link or direct URL) but was not included in the static build because its source file is marked draft: true.

Trellis excludes draft files from routing. If a sidebar category or doc item points to a file with draft: true in its frontmatter, that route is never generated — causing a 500 when navigated to.

Fix: Either remove draft: true from the frontmatter, or remove the entry from the sidebar.

# ❌ File is linked in the sidebar but excluded from the build
---
title: My Page
draft: true   # remove this line to publish
---

# ✅ Published
---
title: My Page
---

grep -rl "draft: true" content/docs/

Language 'X' is not included in this bundle

Full error:

Error [ShikiError]: Language `CSS` is not included in this bundle.
You may want to load it from external source.

Cause: The language identifier in a fenced code block uses the wrong case. Shiki language identifiers are lowercase only. Writing ```CSS instead of ```css causes this error.

Fix: Lowercase all language identifiers in code fences.

{/* ❌ Uppercase — Shiki won't recognize it */}
```CSS
.example { color: red; }
```

{/* ✅ Lowercase */}
```css
.example { color: red; }
```

Common casing mistakes:

Export encountered an error on /(docs)/[...slug]/page

Full error:

Export encountered an error on /(docs)/[...slug]/page: /some-path, exiting the build.

Cause: This is a wrapper error — it means prerendering the page at /some-path failed. The actual cause appears in the error above this line. Common underlying causes:

• The file has draft: true and is linked in the sidebar (see Page is missing param)
• A code block uses an unrecognized language identifier (see Language not included)
• An @include directive points to a file that doesn't exist
• An MDX component is used that hasn't been registered (see Expected component to be defined)

Fix: Read the full error output above this line to identify the root cause, then apply the appropriate fix.

Could not parse expression with acorn

Full error:

[Error: [next-mdx-remote] error compiling MDX:
Could not parse expression with acorn

Cause: MDX treats anything inside { } as a JavaScript expression. Common triggers:

• Custom heading IDs like ### Authors {#authors} — the {#authors} syntax is not supported by MDX (it requires a remark plugin like remark-heading-id). MDX tries to parse #authors as JavaScript and fails.
• Unescaped braces in prose text, such as the result is {x: 1}.

Fix: Remove or escape the braces:

{/* ❌ Custom heading ID — MDX can't parse this */}
### Authors {#authors}

{/* ✅ Remove the ID — rehype-slug auto-generates it from the heading text */}
### Authors

{/* ✅ Or escape the braces */}
### Authors \{#authors\}

@include file not found

Full error:

Error: Include target not found: ../includes/_my-partial.mdx

Cause: An @include directive in an MDX file references a partial that doesn't exist at the specified path, or the path is wrong.

Fix: Verify the path is correct relative to the file containing the @include. Partial files must be prefixed with _ and placed inside an includes directory.

{/* ❌ Wrong path */}
@include includes/_my-partial.mdx

{/* ✅ Relative path from the current file */}
@include ../_includes/_my-partial.mdx

{/* ✅ Root-relative path (from content/docs/) */}
@include /_includes/_my-partial.mdx

Expected component 'X' to be defined

Full error:

Error occurred prerendering page "/some-path". Read more: https://nextjs.org/docs/messages/prerender-error
[Error: Expected component `MyComponent` to be defined: you likely forgot to import, pass, or provide it.] {
  digest: '4264812099'
}
Export encountered an error on /(docs)/[...slug]/page: /some-path, exiting the build.

Cause: An MDX page uses a component (<MyComponent />) that hasn't been registered in the global MDX components map. Trellis renders MDX at build time — every custom component used in content must be explicitly listed in the component registry.

Fix: Register the component in components/docs/mdx/index.tsx:

1. Import your component:

import { MyComponent } from '@/components/custom/my-component'

2. Add it to the mdxComponents object:

export const mdxComponents: Record<string, React.ComponentType<any>> = {
  // ... existing components
  MyComponent,
}

The key name in mdxComponents must match the tag name used in MDX exactly (case-sensitive). For example, if your MDX uses <UxSidebarRedesign />, the registry entry must be UxSidebarRedesign.

Currently registered components:

rm: cannot remove '.next/trace': Permission denied (Windows)

Full error:

rm: cannot remove '.next/trace': Permission denied

Cause: On Windows, the .next/trace file is locked by a running Node process (usually the dev server or a stalled build). Unlike macOS/Linux, Windows doesn't allow deleting files that are open by another process.

Fix: Kill all Node processes first, then delete the folder:

# PowerShell
Stop-Process -Name node -Force; Remove-Item -Recurse -Force .next

# Git Bash / WSL
taskkill //F //IM node.exe && rm -rf .next

If the file is still locked, close VS Code (which runs its own Node processes), delete the folder, then reopen.

TypeScript errors in config/site.ts or config/sidebar.ts

Cause: A misconfigured field in your site configuration (wrong type, missing required field, or an invalid value for an enum field).

Common examples:

• defaultMode set to a value other than 'light', 'dark', or 'system'
• A sidebar item with type: 'doc' missing the id field
• A category link pointing to an id that doesn't match any content file

Fix: Check the TypeScript type definitions at the top of each config file and ensure all values match the expected types. Your editor's type-checking will underline invalid values.