Troubleshooting

For: Anyone whose Kukui setup, build, content, or deployment isn't working as expected.

In this guide you'll: Find fixes for the most common issues — config, build failures, wikilinks and directives, dev server and watcher, and deployment (S3, CloudFront, rsync). Each section uses a problem → cause → fix pattern.

Where to look (quick map)

Quick checklist (check first)

Before digging into a section, rule out the usual causes:

• Config files present? You need system-config.json at project root (with siteRoot) and sites.json under that site root with at least one site. See Setup and config.
• SITE_ID set? If you have multiple sites, set SITE_ID (or DEPLOY_SITE) so the right site is used for dev and deploy. See Setup and config.
• Build completed? Run yarn build and check for errors. If the build fails, see Build failures.
• Deploy target in sites.json? For S3 deploy, your site entry must have s3.bucket (and optionally cloudfront.distributionId). For rsync, rsync.host. See Deployment.

Setup and config

Problem: App won't start or says config is missing.

Cause: system-config.json or sites.json is missing, invalid, or siteRoot doesn't point to a directory that contains sites.json and your site folder.

Fix:

1. Ensure system-config.json exists at the project root with a valid siteRoot path (e.g. "./sites").
2. Ensure that path contains sites.json with a sites object and at least one site (with hostname).
3. If you have no site yet, run yarn wizard to create system-config.json, sites.json, and provision a site from the skeleton.
4. If you have multiple sites, set SITE_ID (or DEPLOY_SITE) to the site ID (e.g. example.com) you want to use.

Problem: Wrong site is used when I run yarn dev or yarn deploy.

Cause: defaultSiteId in sites.json might not match what you expect, or SITE_ID / DEPLOY_SITE is not set (or is set to another site).

Fix: Set SITE_ID (or DEPLOY_SITE) in your environment before running commands, e.g. SITE_ID=live.example.com yarn dev, or set it in .env. Check defaultSiteId in sites.json if you're not setting SITE_ID.

Build failures

Problem: yarn build fails with a frontmatter or YAML error.

Cause: Invalid YAML in the frontmatter of a markdown file (e.g. unquoted colons, wrong indentation, or invalid structure).

Fix: Open the file mentioned in the error; fix the YAML between the opening and closing ---. Use quotes for values that contain :, #, or special characters. Ensure lists use consistent indentation.

Problem: Build fails with "wikilink target not found" or route errors.

Cause: A markdown file references [[Page Name]] or [[Folder/Page]] but the target note doesn't exist or the path is wrong. Route verification may also fail if expected HTML files are missing.

Fix: Create the missing note or correct the wikilink (case-sensitive). Ensure the target file exists under the obsidian folder. If the build reports missing routes, add the missing content or adjust verification in sites.json (e.g. turn off failOnMissingRoutes temporarily).

Problem: Build fails due to special characters or filenames.

Cause: Filenames or paths with characters that are invalid or reserved on the target system can break the build or URL generation.

Fix: Use alphanumerics, hyphens, and underscores in filenames and slug values. Avoid spaces and special characters in folder/file names when possible; if you keep them, ensure slug in frontmatter gives a clean URL.

Problem: Next.js or generator (nav, albums, audio) errors during build.

Cause: A generator might have failed (e.g. missing album.json, bad JSON, or a broken path). Route verification might also fail if critical routes are missing.

Fix: Run generators individually to see which fails: yarn generate:nav, yarn generate:albums, yarn generate:audio. Fix the reported file or config. For route verification, run yarn workspace @obsidian-site/build-tools verify-routes --verbose to see which routes are missing.

Content and authoring

Problem: Wikilinks show as plain text or don't resolve.

Cause: Link target doesn't exist, or the name/path is wrong. Wikilink resolution is case-sensitive.

Fix: Check spelling and case. Use the full path if the note is in another folder: [[Folder/Note Name]]. Ensure the target markdown file exists under the obsidian directory. See Authors-Guide for wikilink and transclusion rules.

Problem: YouTube or Vimeo (or another directive) doesn't embed.

Cause: Syntax is wrong (e.g. missing #, spaces, or wrong ID format). YouTube IDs are 11 characters; Vimeo IDs are numeric.

Fix: Use exact syntax: <Youtube id="VIDEO_ID" title="Title" /> and <Vimeo id="id" title="Title" />. No spaces around #. Get the YouTube ID from the URL (v=...); get the Vimeo ID from the video URL. See Authors-Guide for the directive table.

Problem: Transclusion shows [Transclusion target not found] or [Circular transclusion].

Cause: The embedded note doesn't exist, or note A embeds B and B (directly or indirectly) embeds A.

Fix: Create the target note or fix the path. Remove the circular embed (break the cycle by removing one of the *[Transclusion target not found]* references). See Authors-Guide for transclusion and intro-note conventions.

Problem: Styles or Tailwind classes don't apply.

Cause: Global CSS not loaded, or Tailwind not processing the right content. In Kukui, theme and styles are driven by content.json and (optionally) per-site tailwind.config.json.

Fix: Ensure your site has a valid content.json and that the build completed. For custom Tailwind, add a tailwind.config.json (or .js) in your site directory under the site root. Don't rely on project-root app/globals.css alone for site-specific overrides — use the theme and per-site config.

Development

Problem: Dev server doesn't pick up changes to markdown or assets.

Cause: Next.js cache or the watcher not running. In dev, navigation and some data are regenerated on demand or by the watcher.

Fix: Run yarn watch in a second terminal so generators run on file changes and the Next.js cache is invalidated. If you're not using the watcher, run yarn generate:nav (or the relevant generator) after changing content, then refresh. Restart yarn dev if the server seems stuck.

Problem: Symlink or permission errors when running dev or copy-assets.

Cause: The build or dev setup creates symlinks; some environments or permissions block that.

Fix: Set DISABLE_SYMLINK=true in your environment (or .env) so the process copies files instead of symlinking.

Problem: Output or public directory not where I expect.

Cause: outDir in sites.json (or the default) determines where the built site is written. Dev uses a different layout (e.g. .next, public).

Fix: Check sites.json for your site's outDir. After yarn build, the static site is under that path. Use yarn preview to serve it locally. See Developers-Reference for build phases and structure.

Deployment

Problem: S3 deploy fails — "bucket not found" or "access denied."

Cause: s3.bucket or s3.region in sites.json is wrong, or AWS credentials don't have permission to that bucket. S3 target is read only from sites.json (not from .env).

Fix: Verify sites.json has the correct s3.bucket and s3.region for the site (and SITE_ID is set if you have multiple sites). Ensure your AWS CLI or environment has credentials that can read/write the bucket. Do not put the bucket name in .env — it's ignored for S3.

Problem: Images (or assets) don't load after deploy.

Cause: cdn.hostname (or siteURL) in content.json is wrong or was changed after the last build. Generated indexes (e.g. album) contain URLs built from that config.

Fix: Set cdn.hostname and siteURL correctly in your site's content.json. Then run yarn build again so indexes and asset URLs are regenerated. Redeploy. See Deployment-Guide for config.

Problem: 404s on the live site (pages or assets).

Cause: Files weren't uploaded, or paths don't match. For SPAs, the server may need to serve index.html for client-side routes.

Fix: Ensure yarn build completed and the out directory was synced (e.g. yarn deploy). Check CloudFront (or your server) error pages: 404 (and sometimes 403) should serve /index.html or /404.html as configured. See Deployment-Guide and AWS docs for CloudFront error pages.

Problem: SSL certificate errors with CloudFront.

Cause: CloudFront only uses certificates from us-east-1 (N. Virginia). Certificate in another region or not attached to the distribution.

Fix: Request or import the certificate in us-east-1 in ACM. Attach it to the CloudFront distribution under "Alternate domain names" and "Custom SSL certificate." Validate via DNS if required.

Problem: Updates don't appear after deploy (stale content).

Cause: CloudFront (or browser) cache is serving old content.

Fix: Trigger a CloudFront invalidation after deploy (e.g. /* or /assets/*). yarn deploy usually does this when cloudfront.distributionId is set. Use appropriate cache headers: short or no-cache for HTML/JSON, long-lived for hashed static assets.

Problem: Rsync deploy fails (connection or permission).

Cause: rsync.host in sites.json (or DEPLOY_HOST in .env) is wrong, or SSH key/auth isn't set up for the target host.

Fix: Verify rsync.host (e.g. user@host.example.com:/path). Test SSH: ssh user@host.example.com. Use ssh-agent or the correct key so rsync can authenticate. See Deployment-Guide for rsync option.

See also

• Quick-Start-Guide — Setup and first run
• Authors-Guide — Content, wikilinks, and directives
• Developers-Reference — Config and CLI
• Deployment-Guide — Deploy commands and AWS/rsync