Troubleshooting

Common problems and how to fix them.

---

My new file doesn’t appear on the site

Root cause: The file is missing publish: true in its frontmatter. karaoke-cms is private-by-default — any file without publish: true is treated as a private vault note and never included in the build.

Fix: Add publish: true to the file’s frontmatter:

---
title: "My Page"
publish: true
---

This is intentional, not a bug. Files silently stay private — no error is shown.

---

Search doesn’t work or shows no results

Root cause: The search module is powered by Pagefind, which indexes your built HTML. It requires a production build to generate the index — it cannot index content that hasn’t been built yet.

Fix: Run a full build first:

pnpm build
# or
npm run build

After building, pnpm dev (or pnpm preview) will serve the Pagefind index and search will work. Re-run the build any time you add new content you want indexed.

---

I changed my vault path but the old content still shows

Root cause: Astro caches content collection metadata in .astro/. After changing KARAOKE_VAULT in .env or .env.default, the cache still points to the old vault location.

Fix: Delete the Astro content cache, then restart the dev server:

rm -rf apps/website/.astro
pnpm dev

Do this any time you change the KARAOKE_VAULT value.

---

The comments widget doesn’t appear

Root cause — missing module: The comments() module must be present in modules[] in karaoke.config.ts. Even if blog({ comments: true }) is set, the widget won’t render without the module registered.

Root cause — missing Giscus config: The comments() module requires a repo, repoId, category, and categoryId. If any value is wrong or missing, the widget won’t load.

Fix: Make sure your config includes comments() with valid Giscus values:

modules: [
  blog({ mount: '/blog', comments: true }),
  comments({
    repo: "owner/repo",
    repoId: "R_...",
    category: "General",
    categoryId: "DIC_...",
  }),
],

Get the correct values from giscus.app. GitHub Discussions must be enabled on the repo.

---

My wikilink shows as plain text instead of a link

Root cause: The target page is not published. Wikilinks only resolve to clickable links when the target file has publish: true. If the target is a private note, the link renders as plain text by design.

Fix: Add publish: true to the frontmatter of the page you are linking to, or remove the wikilink if the target should stay private.

---

The /karaoke-cms section is gone in production

Root cause: This is expected. The karaoke-cms collection is dev-only by default (modes: ['dev']). It is intentionally excluded from production builds and will never appear on your deployed site.

No fix needed. If you need to access the handbook, run the dev server locally with pnpm dev.

To override this and ship the handbook to production, add to karaoke.config.ts:

collections: {
  'karaoke-cms': { modes: ['dev', 'prod'] },
},

---

OG images aren’t generating

Root cause — missing module: The seo() module must be in modules[]. OG image generation is provided exclusively by this module.

Root cause — checking in dev: OG images are only generated during a production build (pnpm build). They do not run during pnpm dev.

Fix: Add seo() to your modules and run a full build:

modules: [
  // ...
  seo(),
],

Then:

pnpm build

---

Tag pages are empty

Root cause: The tags: field is missing or misspelled in the frontmatter of your content files. The tags() module builds its index from the tags frontmatter field — if it’s absent or uses a different key (e.g., tag: singular), no entries will appear.

Fix: Make sure published files use tags: (plural) as a YAML list:

---
title: "My Post"
publish: true
tags:
  - tutorial
  - astro
---

---

The deploy fails at the privacy check

Root cause: A file that should be private ended up in dist/. This can happen if a file was accidentally given publish: true, or if the build included content it shouldn’t have.

Fix: Run the privacy check locally to identify the offending file:

node scripts/assert-privacy.js dist

The script will report which paths in dist/ shouldn’t be there. Remove publish: true from the relevant file (or correct whatever caused it to be built), then rebuild.

---

AI enrichment isn’t running on commit

Root cause: The enrichment pre-commit hook requires either OPENAI_API_KEY or ANTHROPIC_API_KEY to be set in your environment. If neither key is present, the hook exits silently without enriching anything — no error is shown.

Fix: Set one of the API keys in your shell environment or in a local .env file (gitignored):

export OPENAI_API_KEY=sk-...
# or
export ANTHROPIC_API_KEY=sk-ant-...

Then make a commit — the hook will run and enrich staged files automatically.

---

docs() collection entries are missing from search

Root cause: Search indexes all published pages. If a docs page is missing from search results, the most likely cause is that the page does not have publish: true in its frontmatter.

Fix: Verify that the missing docs pages have publish: true, then run a full build to regenerate the Pagefind index:

pnpm build

---

Two docs pages with the same filename but different folders collide

Root cause: Astro collection entries are keyed by filename (without extension). If two files share the same name — even if they are in different subdirectories — they produce the same slug and one silently overwrites the other in the collection.

Fix: Rename one of the files so all filenames within a docs section are unique:

docs/
  getting-started.md        ✓
  api/getting-started.md    ✗  collides — rename to api-getting-started.md

Unique filenames across the entire docs folder prevent slug collisions.