chill.social/themes/chill-theme/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Common issues and solutions when working with the Hugo Saasify Theme. Find quick fixes for installation, build, styling, content, deployment, and performance problems.

Table of Contents

• Installation Issues
• Build Errors
• Styling Problems
• Content Issues
• Deployment Problems
• Performance Issues
• Browser Compatibility
• Getting Help

Installation Issues

Theme Not Found

Problem: Hugo can't find the theme

Error: unable to locate theme directory "chill-theme"

Solutions:

1. Verify theme directory exists:

ls themes/chill-theme

2. Check theme name in config:

# hugo.toml
theme = "chill-theme"  # Must match directory name exactly

3. If using Git submodule, initialize it:

git submodule init
git submodule update --recursive

4. Check directory structure:

# Should show theme files
ls -la themes/chill-theme/layouts/

Hugo Extended Not Installed

Problem: Error about Hugo Extended being required

Error: this theme requires Hugo Extended

Solutions:

1. Check your Hugo version:

hugo version

Expected output should include "extended":

hugo v0.120.0+extended darwin/amd64

2. Install Hugo Extended:

   • Visit Hugo Releases
   • Download version with "extended" in the name
   • Install and verify

3. On macOS with Homebrew:

brew install hugo

Submodule Empty

Problem: Theme directory exists but is empty

Solutions:

1. Update submodules:

git submodule update --init --recursive

2. If still empty, remove and re-add:

git submodule deinit -f themes/chill-theme
rm -rf .git/modules/themes/chill-theme
git rm -f themes/chill-theme
git submodule add https://github.com/chaoming/chill-theme.git themes/chill-theme

npm Dependencies Failed

Problem: npm install fails

npm ERR! code ENOENT

Solutions:

1. Check Node.js is installed:

node --version
npm --version

2. Ensure config files are copied to site root:

cp themes/chill-theme/package.json .
cp themes/chill-theme/postcss.config.js .
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js

3. Clear npm cache:

npm cache clean --force

4. Delete and reinstall:

rm -rf node_modules package-lock.json
npm install

5. Use different npm registry (if blocked):

npm config set registry https://registry.npmjs.org/
npm install

Build Errors

Tailwind CSS Not Processing

Problem: Site loads without styling

Solutions:

1. Enable build stats in hugo.toml:

[build]
  writeStats = true

[build.buildStats]
  enable = true

2. Clear Hugo cache:

hugo --gc

3. Verify Tailwind config exists:

ls themes/chill-theme/tailwind.config.js

4. Rebuild from clean state:

rm -rf public resources
hugo server -D

Template Errors

Problem: Error in template execution

Error: error calling partial: template: partials/header.html...

Solutions:

1. Check the error message - it usually points to the specific line

2. Common causes:

   • Missing closing tags
   • Incorrect variable names
   • Missing required parameters
   • Syntax errors in shortcodes

3. Validate configuration:

hugo config

4. Test with minimal config:
   • Copy exampleSite/hugo.toml
   • Gradually add your customizations

Shortcode Errors

Problem: Shortcode fails to render

Error: failed to render shortcode "pricing-table-1"

Solutions:

1. Check JSON syntax (for shortcodes accepting JSON):

   • Use double quotes, not single quotes
   • No trailing commas
   • Valid JSON structure
   • Use JSON validator online

2. Verify shortcode exists:

ls themes/chill-theme/layouts/shortcodes/pricing-table-1.html

3. Check shortcode syntax:

# Correct
{{< shortcode-name >}}

# Incorrect
{< shortcode-name >}     # Missing one brace
{{<shortcode-name>}}     # Missing spaces

Build Fails in CI/CD

Problem: Builds work locally but fail in CI

Solutions:

1. Match Hugo versions:

   • Check local: hugo version
   • Set in CI config: HUGO_VERSION=0.120.0

2. Install theme dependencies:

# GitHub Actions example
- name: Install dependencies
  run: |
    cp themes/chill-theme/package.json .
    cp themes/chill-theme/postcss.config.js .
    cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
    npm install

3. Check environment variables:

   • Verify all required env vars are set
   • Check for typos in variable names

4. Review build logs:

   • Look for specific error messages
   • Check file paths are correct
   • Verify permissions

Styling Problems

Custom CSS Not Loading

Problem: Custom CSS changes don't appear

Solutions:

1. Clear browser cache:

   • Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
   • Or use incognito/private mode

2. Verify CSS file path:

[params]
  customCSS = ["css/custom.css"]  # File must be in static/css/

3. Check file exists:

ls static/css/custom.css

4. Clear Hugo cache:

hugo --gc
rm -rf resources
hugo server -D

Tailwind Classes Not Working

Problem: Tailwind utility classes have no effect

Solutions:

1. Check class is in content paths:

// tailwind.config.js
content: ["./layouts/**/*.html"]

2. Avoid dynamic class names:

<!-- Don't do this -->
<div class="text-{{ .Color }}-600">

<!-- Do this instead -->
<div class="{{ if eq .Color "blue" }}text-blue-600{{ end }}">

3. Rebuild site:

hugo --gc
hugo

4. Check Tailwind version compatibility:

npm list tailwindcss

Colors Not Matching Design

Problem: Colors appear different than expected

Solutions:

1. Check color values in tailwind.config.js:

colors: {
  primary: {
    600: '#425ad6',  // Your primary color
  }
}

2. Verify you're using correct shade:

<div class="bg-primary-600">  <!-- Not bg-primary -->

3. Check for color overrides in custom CSS

4. Test in different browsers to rule out rendering differences

Responsive Design Issues

Problem: Layout broken on mobile/tablet

Solutions:

1. Test with DevTools:

   • Open Chrome DevTools (F12)
   • Toggle device toolbar (Ctrl+Shift+M)
   • Test various screen sizes

2. Check responsive classes:

<!-- Use responsive prefixes -->
<div class="text-sm md:text-base lg:text-lg">

3. Verify viewport meta tag (should be in baseof.html):

<meta name="viewport" content="width=device-width, initial-scale=1.0">

4. Test breakpoints:
   • sm: 640px
   • md: 768px
   • lg: 1024px
   • xl: 1280px

Content Issues

Page Not Rendering

Problem: Page exists but shows 404

Solutions:

1. Check front matter:

---
title: "My Page"
draft: false  # Make sure this is false
---

2. Verify file location:

ls content/my-page.md

3. Check URL structure:

   • content/about.md → /about/
   • content/blog/post.md → /blog/post/

4. Restart server:

hugo server -D  # -D shows drafts

Images Not Displaying

Problem: Images don't show on page

Solutions:

1. Check file path:

# Correct - absolute from static/
![Image](/images/photo.jpg)

# Incorrect - relative path
![Image](../images/photo.jpg)

2. Verify file exists:

ls static/images/photo.jpg

3. Check file permissions:

chmod 644 static/images/photo.jpg

4. Test URL directly:

   • Visit http://localhost:1313/images/photo.jpg
   • Should display the image

5. Check file extension matches exactly (case-sensitive on some systems)

Shortcode Shows as Text

Problem: Shortcode appears as plain text instead of rendering

Solutions:

1. Check syntax:

# Correct
{{< shortcode >}}

# Incorrect
{{ < shortcode > }}
{< shortcode >}

2. Verify shortcode exists:

ls themes/chill-theme/layouts/shortcodes/

3. Check if content uses correct format:
   • Markdown files: Use {{< >}}
   • HTML files: Use {{ .Inner }}

Taxonomy Pages Empty

Problem: Category or tag pages show no posts

Solutions:

1. Enable taxonomies in hugo.toml:

[taxonomies]
  category = 'categories'
  tag = 'tags'

2. Check front matter:

categories: ["Technology"]  # Use array, not string
tags: ["Hugo", "Tutorial"]

3. Verify taxonomy matches config:

# If you have:
[taxonomies]
  category = 'categories'

# Use in front matter:
categories: ["Tech"]  # Not category:

Deployment Problems

Build Fails on Platform

Problem: Build works locally but fails on Netlify/Vercel/etc.

Solutions:

1. Set Hugo version:

Netlify:

# netlify.toml
[build.environment]
  HUGO_VERSION = "0.120.0"

Vercel:

// vercel.json
{
  "build": {
    "env": {
      "HUGO_VERSION": "0.120.0"
    }
  }
}

2. Install theme dependencies:

Add to build command:

cp themes/chill-theme/package.json . && cp themes/chill-theme/postcss.config.js . && cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js && npm install && hugo --minify

3. Check environment variables are set in platform UI

Assets Not Loading After Deploy

Problem: CSS/JS/images don't load on deployed site

Solutions:

1. Verify baseURL in hugo.toml:

baseURL = "https://yourdomain.com/"  # Must match your domain

2. Use absolute paths:

<!-- Correct -->
<img src="/images/logo.svg">

<!-- Incorrect -->
<img src="images/logo.svg">

3. Check CDN/cache:

   • Clear CDN cache
   • Wait for propagation
   • Hard refresh browser

4. Verify build output:

# Check public/ directory
ls -la public/css/
ls -la public/images/

SSL Certificate Issues

Problem: HTTPS not working or certificate errors

Solutions:

1. Wait for provisioning (can take 24-48 hours)

2. Check DNS configuration:

   • A record points to correct IP
   • CNAME points to correct host

3. Force HTTPS in platform settings

4. Clear browser SSL cache

404 on Deployed Site

Problem: Pages work locally but 404 on deployed site

Solutions:

1. Check baseURL includes trailing slash:

baseURL = "https://example.com/"  # Note the /

2. Verify case sensitivity:

   • URLs are case-sensitive on most servers
   • Use lowercase for consistency

3. Check redirects (if you have them):

   • Verify redirect rules are correct
   • Check for infinite redirect loops

Performance Issues

Slow Build Times

Problem: Site takes too long to build

Solutions:

1. Enable caching:

[caches]
  [caches.images]
    dir = ":resourceDir/_gen"
    maxAge = "1440h"

2. Optimize images before adding:

   • Compress images
   • Reduce dimensions
   • Use appropriate formats

3. Limit content during development:

hugo server -D --buildFuture=false --buildExpired=false

4. Check for template loops:
   • Review custom templates
   • Look for inefficient queries

Site Loads Slowly

Problem: Pages take long time to load in browser

Solutions:

1. Enable minification:

hugo --minify

2. Optimize images:

   • Compress all images
   • Use WebP format
   • Implement lazy loading

3. Use CDN for static assets

4. Enable caching on server:

# Nginx example
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    expires 1y;
}

5. Run Lighthouse audit:
   • Open Chrome DevTools
   • Go to Lighthouse tab
   • Run performance audit
   • Follow recommendations

Large CSS File

Problem: Generated CSS is too large

Solutions:

1. Verify PurgeCSS is working:

# Check file size
ls -lh public/css/*.css

2. Ensure build stats enabled:

[build]
  writeStats = true

3. Check content paths in tailwind.config.js:

content: ["./layouts/**/*.html"]

Browser Compatibility

Works in Chrome, Not Safari

Problem: Site works in Chrome but has issues in Safari

Solutions:

1. Check for unsupported CSS:

   • Avoid bleeding-edge features
   • Test CSS properties on Can I Use

2. Add vendor prefixes if needed:

-webkit-transition: all 0.3s;
transition: all 0.3s;

3. Test in multiple browsers:
   • Chrome
   • Firefox
   • Safari
   • Edge

JavaScript Errors in IE11

Problem: Site broken in Internet Explorer

Note: IE11 is deprecated. Modern browsers only.

Solutions:

1. Display upgrade message for old browsers
2. Focus on modern browsers (Chrome, Firefox, Safari, Edge)
3. IE11 usage is <1% globally - consider if support is needed

Getting Help

Before Asking for Help

1. Check this guide for your issue
2. Review documentation:
   • INSTALLATION.md
   • CONFIGURATION.md
   • LAYOUTS.md
   • SHORTCODES.md
3. Search existing issues on GitHub
4. Try example site to isolate problem

Gathering Information

When reporting issues, include:

1. Hugo version:

hugo version

2. Operating system:

uname -a  # Linux/Mac
# or
ver  # Windows

3. Error messages (complete output)

4. Configuration (relevant parts of hugo.toml)

5. Steps to reproduce:

   • What you did
   • What you expected
   • What actually happened

6. Minimal reproduction:

   • Simplest case that shows the problem
   • Remove unrelated code/config

Where to Get Help

1. Documentation: Check all docs in /docs directory

2. Example Site: Review working examples in /exampleSite

3. GitHub Issues:

   • Search: Existing Issues
   • Create: New Issue

4. Hugo Community:

   • Hugo Discourse
   • Hugo Documentation

5. Stack Overflow:

   • Tag: hugo, hugo-theme

Creating a Good Issue Report

Template:

## Description
Brief description of the problem

## Environment
- Hugo version: 0.120.0+extended
- OS: macOS 14.0
- Theme version: main branch

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Error Messages

Paste error messages here

## Configuration
```toml
Relevant parts of hugo.toml

Additional Context

Any other relevant information

## Common Error Messages

### "Page Not Found"

**Cause**: Content file doesn't exist or is draft

**Fix**:
- Check file exists
- Verify `draft: false`
- Restart server

### "Template Not Found"

**Cause**: Missing or misnamed template file

**Fix**:
- Check template file exists
- Verify layout name in front matter
- Check template lookup order

### "Failed to Process"

**Cause**: CSS/Asset processing error

**Fix**:
- Check PostCSS configuration
- Verify Hugo Extended installed
- Review asset file syntax

### "Submodule Not Found"

**Cause**: Git submodule not initialized

**Fix**:
```bash
git submodule update --init --recursive

Quick Fixes Checklist

When something isn't working:

• Restart Hugo server
• Clear browser cache (Ctrl+Shift+R)
• Clear Hugo cache (hugo --gc)
• Delete public/ and resources/ directories
• Verify Hugo version (hugo version)
• Check hugo.toml syntax
• Review error messages carefully
• Test with example site configuration
• Check file permissions
• Verify file paths are correct

Prevention Best Practices

Avoid issues before they happen:

1. Use Version Control: Commit working states
2. Test Locally: Before deploying
3. Keep Updated: Update Hugo and dependencies
4. Follow Documentation: Don't guess
5. Start Simple: Add complexity gradually
6. Backup Configuration: Save working configs
7. Use Example Site: Reference working examples
8. Read Error Messages: They usually tell you what's wrong

Related Documentation

• INSTALLATION.md - Installation guide
• CONFIGURATION.md - Configuration options
• DEPLOYMENT.md - Deployment guides
• Hugo Troubleshooting

Still Stuck?

If you've tried everything and still have issues:

1. Create minimal reproduction - Simplest case showing problem
2. Open GitHub issue with all relevant information
3. Be patient - Maintainers are volunteers
4. Be detailed - More info = faster resolution
5. Follow up - Respond to questions

Remember: Most issues have been encountered before. Search first, then ask.