Troubleshooting

This page covers common issues you may encounter when working with Pagesmith and how to resolve them.

Dev Server Issues

Dev server doesn’t reload on file changes

Symptoms: You edit a markdown file or configuration file, but the browser does not refresh.

Causes and solutions:

1. File is outside contentDir. The dev server watches only the content directory configured in pagesmith.config.json5. Verify your file is inside the correct directory:

   pagesmith.config.json5

   1{2  contentDir: "./content", // Files must be under this path3}

   The default contentDir is docs/ if that directory exists, otherwise content/. Check which applies to your project.

2. Syntax error in frontmatter. A YAML parsing error in frontmatter can cause the build to fail silently. Check for common YAML issues:

   Common YAML mistakes

   1---2# Missing quotes around values with colons3title: Getting Started: A Guide    # Needs quotes4title: "Getting Started: A Guide"  # Correct56# Incorrect indentation7hero:8title: My Site    # Wrong -- needs indentation9  title: My Site  # Correct10---

3. File watcher limit reached. On Linux, the default inotify watch limit may be too low. Increase it:

   Terminal

   1echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf2sudo sysctl -p

Build Errors

Build fails with “cannot find module virtual:content/…”

Symptoms: The build or dev server crashes with an error like:

1Error: Cannot find module 'virtual:content/posts'

Causes and solutions:

1. Collection name mismatch. The virtual module name must match the collection name in your content.config.ts exactly:

   content.config.tsapp.ts

   Copy

   content.config.ts

   1const posts = defineCollection({2  loader: "markdown",3  directory: "content/posts",4});56export default defineConfig({7  collections: { posts }, // This name must match the import8});

   app.ts

   1// Must match the key in collections2import posts from "virtual:content/posts"; // Correct3import blog from "virtual:content/blog"; // Wrong -- no collection named 'blog'

2. Missing content.config.ts. The Vite plugin pagesmithContent looks for this file at the project root. Ensure it exists and exports a valid config.

3. Plugin not registered. Ensure the pagesmithContent Vite plugin is in your vite.config.ts:

   vite.config.ts

   1import { pagesmithContent } from "@pagesmith/site/vite";2import { defineConfig } from "vite";34export default defineConfig({5  plugins: [pagesmithContent()],6});

Build fails with validation errors

Symptoms: The build reports schema validation errors for your content entries.

Causes and solutions:

1. Required field missing. If you use BaseFrontmatterSchema or BlogFrontmatterSchema, fields like title, description, and publishedDate are required:

   Missing required fields

   1---2title: My Post3# Missing 'description' and 'publishedDate' -- will fail validation4---

   Add the missing fields or make them optional in a custom schema:

   Optional description

   1const posts = defineCollection({2  schema: z.object({3    title: z.string(),4    description: z.string().optional(), // Now optional5  }),6});

2. Type mismatch. A field value does not match the expected type. Common cases:

   Type mismatches

   1---2# order expects a number, not a string3order: "first"   # Wrong4order: 1         # Correct56# tags expects an array7tags: javascript  # Wrong -- this is a string8tags:             # Correct -- this is an array9  - javascript10---

Search Issues

Search isn’t working

Symptoms: The search modal opens (via Ctrl+K / Cmd+K) but returns no results, or the search UI does not appear at all.

Causes and solutions:

1. Search index not built. Pagefind generates its index during pagesmith-docs build, not during development. Run a full build first:

   Terminal

   1pagesmith-docs build2pagesmith-docs preview

   During pagesmith-docs dev, search is not available because the Pagefind index has not been generated.

2. Search disabled in config. Check that search is enabled:

   pagesmith.config.json5

   1{2  search: {3    enabled: true, // Default is true4  },5}

3. Content not indexed. Pagefind indexes the built HTML output. If pages are marked as draft: true, they are excluded from the build and will not appear in search results.

Layout Issues

Custom layout isn’t being used

Symptoms: You created a custom layout component, but pages still render with the default layout.

Causes and solutions:

1. Layout not registered in config. Custom layouts must be declared in the theme.layouts config:

   pagesmith.config.json5

   1{2  theme: {3    layouts: {4      home: "./theme/layouts/CustomHome.tsx",5      page: "./theme/layouts/CustomPage.tsx",6    },7  },8}

2. Export name mismatch. The layout module must export the component as default or one of the recognized named exports:

   Layout Key	Accepted Exports
   home	default, DocHome, Home
   page	default, DocPage, Page
   notFound	default, DocNotFound, NotFound

   theme/layouts/CustomPage.tsx

   1// Either of these works:2export default function CustomPage(props) { ... }3export function DocPage(props) { ... }

3. Section-level layout not registered. If you set layout or itemLayout in a section’s meta.json5, the layout name must also be a key in theme.layouts:

   content/blog/meta.json5pagesmith.config.json5

   Copy

   content/blog/meta.json5

   1{2  displayName: "Blog",3  itemLayout: "blog-post", // Must exist in theme.layouts4}

   pagesmith.config.json5

   1{2  theme: {3    layouts: {4      "blog-post": "./theme/layouts/BlogPost.tsx",5    },6  },7}

Content Issues

Images not appearing

Symptoms: Images referenced in markdown do not display in the rendered page.

Causes and solutions:

1. Incorrect relative path. Image paths in markdown are relative to the markdown file’s directory. For folder-based content, place images next to the README.md:

   TXTDirectory structureREADME.md

   Copy

   TXTDirectory structure

   1content/2  guide/3    getting-started/4      README.md5      screenshot.png    <- Same directory as README.md

   README.md

   1![Screenshot](./screenshot.png)

2. Image outside content directory. The build copies companion assets (images referenced from markdown) from the content directory. Images placed outside contentDir are not discovered.

3. Unsupported format. The asset copier recognizes these extensions: .svg, .png, .jpg, .jpeg, .gif, .webp, .avif, .ico. Other formats are ignored.

4. Public directory images. For images shared across many pages, place them in publicDir (default: public/) and reference with an absolute path:

   Markdown

   1![Logo](/images/logo.svg)

Validation errors but frontmatter looks correct

Symptoms: The build reports validation errors even though the frontmatter YAML appears correct.

Causes and solutions:

1. Schema type expectations. Check the schema definition for the exact types expected. Zod is strict about types:

   Subtle type issues

   1---2# publishedDate must be a valid date3publishedDate: not-a-date      # Fails4publishedDate: 2026-01-15      # Works56# order must be a number7order: 1.5                      # Works (it's a number)8order: "1"                      # May fail depending on schema9---

2. Required vs. optional fields. BaseFrontmatterSchema requires title, description, and publishedDate. The DocsFrontmatterSchema used by @pagesmith/docs makes all fields optional. If you see “required” errors, check which schema is active.

3. Extra fields with strict schemas. If your custom schema does not use .passthrough(), extra frontmatter fields cause validation failures:

   Strict vs. passthrough

   1// Strict -- extra fields rejected2const schema = z.object({ title: z.string() });34// Passthrough -- extra fields preserved5const schema = z.object({ title: z.string() }).passthrough();

Git-Based Features

lastUpdated shows wrong date

Symptoms: The “Last updated” timestamp on a page does not match when you last edited the file.

Causes and solutions:

1. File not committed. The lastUpdated feature reads the git log with git log -1 --format=%cI. Uncommitted changes are not reflected. Commit your changes to update the timestamp.

2. Shallow clone. CI environments often use shallow clones (git clone --depth 1), which only include the most recent commit. All pages will show the same date. Use a full clone or increase the depth:

   GitHub Actions

   1- uses: actions/checkout@v42  with:3    fetch-depth: 0 # Full history for accurate timestamps

3. Feature not enabled. Ensure lastUpdated is enabled in your config:

   pagesmith.config.json5

   1{2  lastUpdated: true,3}

4. Git not available. If git is not on the system PATH during the build, the timestamp silently falls back to undefined and no date is shown.

Configuration Issues

Config file not found

Symptoms: The CLI exits with:

1No pagesmith.config.json5 file found at /path/to/pagesmith.config.json5

Causes and solutions:

1. Wrong working directory. The CLI looks for the config file relative to the current working directory. Run the command from your project root, or specify the path:

   Terminal

   1pagesmith-docs dev --config ./pagesmith.config.json5

2. File not created yet. Run pagesmith-docs init to create the initial config file:

   Terminal

   1pagesmith-docs init

Base path not applied correctly

Symptoms: Links and assets break when deploying to a subdirectory (e.g. GitHub Pages with a repository name prefix).

Causes and solutions:

The base path follows a priority chain:

1. --base-path CLI flag (highest priority)
2. BASE_URL environment variable
3. basePath in pagesmith.config.json5
4. Default: "/"

Ensure you set it in exactly one place. For GitHub Pages:

1pagesmith-docs build --base-path /my-repo

Or in CI:

1BASE_URL=/my-repo pagesmith-docs build