Troubleshooting

Common issues and their solutions when working with Harold.

Build Errors

Build fails with "Cannot find module"

Symptoms:

Error: Cannot find module 'harold-scripts'

Solution:

Install dependencies: npm install
Ensure harold-scripts is in your package.json (projects created by create-harold-app add it to devDependencies)
Delete node_modules and package-lock.json, then run npm install again

Build fails with "Missing Front Matter keys"

Symptoms:

Missing Front Matter keys for example.md. Required keys are: layout, title, publicationDate. File was not generated!

Solution: Ensure all Markdown files have required front matter fields:

---
layout: 'blog-post'
title: 'My Post Title'
publicationDate: '2025-12-20'
---

All three fields are required for every Markdown file.

"No posts directory found" warning

Symptoms:

No posts directory found. Skipping posts generation.

Solution: This is normal if you don't have a posts directory. Since v1.3.0, directories are optional. To fix:

Create src/posts/ directory if you want blog posts
Or ignore the warning if building a pages-only site

"Could not determine dimensions for image"

Symptoms:

Could not determine dimensions for image: image.jpg

Solution:

For local images: Ensure the image file exists in the correct path

For remote images: Add dimensions manually:

<img src="https://example.com/image.jpg" width="800" height="600" alt="Image" />

Development Server Issues

Dev server won't start - Port already in use

Symptoms:

Error: listen EADDRINUSE: address already in use :::3000

Solution:

Change port: PORT=3001 npm start

Kill existing process:

# Find process using port 3000
lsof -i :3000
# Kill it
kill -9 <PID>

Changes not reflecting in browser

Symptoms: File changes don't appear when refreshing browser.

Solution:

Hard refresh: Ctrl+Shift+R (Cmd+Shift+R on Mac)
Clear build directory: Delete build/ folder and rebuild
Check file watcher: Restart dev server (npm start)
Disable browser cache: Open DevTools > Network tab > Check "Disable cache"

Styling Issues

Styles not loading on first page load

Symptoms: CSS loads on refresh but not on initial load.

Solution: This was fixed in v1.3.0. Update harold-scripts:

npm install harold-scripts@latest

CSS changes not applying

Symptoms: SCSS changes saved but not visible in browser.

Solution:

Hard refresh browser: Ctrl+Shift+R
Check SCSS syntax: Look for compilation errors in terminal
Verify file imports: Ensure partial files have _ prefix and are imported
Clear cache: Delete build/styles/ and restart dev server

Styles work in dev but not in production

Symptoms: Site looks fine locally but broken when deployed.

Solution:

Check paths: Use relativePath helper for all asset paths
Verify hostDirName: If hosting in subdirectory, configure .haroldrc:
```
{
  "hostDirName": "my-subdirectory"
}
```
Build and test locally: Run npm run build and serve the build/ folder

Image Issues

Images not loading / 404 errors

Symptoms: Images show broken icon or 404 in Network tab.

Solution:

Check file exists: Verify image is in src/assets/images/
Use absolute paths: /assets/images/photo.jpg (not ../images/photo.jpg)
Check case sensitivity: Linux servers are case-sensitive (Photo.jpg ≠ photo.jpg)
Verify build output: Check if image exists in build/assets/images/

Images causing layout shift

Symptoms: Page content jumps when images load.

Solution: For v1.3.0+:

Local images: Dimensions are automatic

Remote images: Add width/height manually:

<img src="https://example.com/image.jpg" width="800" height="600" alt="Image" />

Path Issues

Links broken when hosting in subdirectory

Symptoms: Internal links return 404 when site is in subdirectory (e.g., example.com/blog/).

Solution:

Configure .haroldrc:
```
{
  "hostDirName": "blog"
}
```

Use relativePath helper for all links:

<a href="{{relativePath 'about.html'}}">About</a>
<img src="{{relativePath 'assets/images/photo.jpg'}}" />

Absolute paths not working

Symptoms: Paths starting with / don't work.

Solution:

In .hbs files: Use relativePath helper
In .scss files: Use relative paths or configure hostDirName
In Markdown: Use paths relative to the public directory

Configuration Issues

Configuration not loading

Symptoms: Changes to .haroldrc not taking effect.

Solution:

Verify JSON syntax: Use a JSON validator
Restart dev server: Configuration loads at startup
Check location: Place .haroldrc in project root or src/ directory
Check file name: Must be exactly .haroldrc (not .haroldrc.txt)

Custom directory names not working

Symptoms: Changed mdFilesDirName but URLs still use /posts/.

Solution:

Rename actual directory: If config says "docs", rename src/posts/ to src/docs/
Rename layouts directory too: Update mdFilesLayoutsDirName to match
Update search paths: If using search, update paths in harold-search.js
Rebuild completely: Delete build/ and run npm run build

Performance Issues

Build is very slow

Symptoms: Build takes minutes instead of seconds.

Solution:

Check image sizes: Compress large images before adding
Reduce Markdown files: Split large posts into smaller ones
Check for infinite loops: Review custom Handlebars helpers
Update harold-scripts: Newer versions have performance improvements

Site loads slowly

Symptoms: Page takes long to load in browser.

Solution:

Enable minification:

{
  "minifyCss": true,
  "minifyHtml": true
}

Optimize images: Use tools like TinyPNG, Squoosh, or ImageOptim
Use lazy loading: Images automatically lazy load in v1.3.0+
Check hosting: Use CDN or good hosting service

Markdown Issues

HTML in Markdown not rendering

Symptoms: HTML tags appear as text instead of rendering.

Solution: Harold supports raw HTML in Markdown by default. If not working:

Check for special characters: Ensure < and > aren't escaped
Verify tag support: Some script tags are sanitized for security
Use allowed tags: Check sanitization schema in harold-scripts

Markdown syntax not working

Symptoms: Markdown like **bold** or # Heading not rendering.

Solution:

Check file extension: Must be .md or .markdown
Verify front matter: Must have --- delimiters
Check for typos: Markdown syntax must be exact
Test with simple file: Create minimal test case

Deployment Issues

Build succeeds locally but fails on hosting

Symptoms: npm run build works locally but fails on your static host or CI provider.

Solution:

Check Node version: Ensure hosting uses Node 24+

{
  "engines": {
    "node": ">=24.0.0"
  }
}

Verify build command: Should be harold-scripts build
Check package metadata: Projects created by create-harold-app keep harold-scripts in devDependencies, so make sure it is still present there and that your hosting build step installs dev dependencies

Deployed site shows 404s

Symptoms: Pages work locally but return 404 when deployed.

Solution:

Check output directory: Hosting should serve from build/ (or your configured outputDirName)
Verify index.html exists: Must be in root of output directory
Check hosting configuration: Some hosts need specific settings for SPAs
Verify file names: Some hosts are case-sensitive

Getting Help

If you're still stuck:

Check GitHub Issues: harold-js/harold-scripts/issues
Search existing issues: Your problem might already be solved
Create new issue: Include:
- Harold version (npm list harold-scripts)
- Node version (node --version)
- Error messages
- Minimal reproduction steps
Check templates: Review official template repositories for examples

Debugging Tips

Enable verbose logging

Add to your package.json:

{
  "scripts": {
    "start": "DEBUG=* harold-scripts start",
    "build": "DEBUG=* harold-scripts build"
  }
}

Test with minimal setup

Create a minimal test case:

Single page in src/pages/index.hbs
Single stylesheet in src/styles/main.scss
No posts, no partials
Build and verify

Check generated files

Inspect build/ directory:

Are files generated?
Do paths look correct?
Is HTML structure valid?
Are styles present?

Next: Caveats