Troubleshooting

This page covers common issues you may encounter when using Accent CMS, along with their causes and solutions. Use the table of contents to jump to the relevant section.

Page Not Found (404)

A 404 response means Accent CMS could not match the requested URL to any content page. The table below lists the most common causes.

Debugging 404 Errors

1. Check loaded pages. Add ?acdbg to any working page URL and inspect the all_pages list to see every page Accent CMS has loaded. If your page is missing from the list, the problem is in content loading.
2. Run validation. Use accent validate to check content integrity across all pages.
3. Check server logs. The terminal output shows which files are loaded at startup and when content is reloaded.
4. Verify config.yaml. Ensure content.directory points to the correct folder (default: ./content).

Template Rendering Errors

MiniJinja template errors appear in the server logs and sometimes in the browser as a 500 error page. The table below maps common error messages to their solutions.

Debugging Template Errors

• Use {{ debug(page) }} in a template to dump the full page context as formatted output.
• Use {{ debug(site) }} to inspect site-level variables.
• Add ?acdbg to any page URL to open the built-in debug panel without editing templates.
• Enable dev.debug: true in config.yaml and use {% if dev.debug %} blocks for conditional debug output.

Hot Reload Not Working

Hot reload watches for file changes and automatically refreshes the browser. When it stops working, check the following.

Reload configuration

You can reload config.yaml without restarting the server.

pkill -HUP accent

Invoke-RestMethod -Method Post -Uri http://127.0.0.1:4400/_admin/reload

POST /_admin/reload works on every platform. In production mode it needs the admin token in an Authorization: Bearer <token> or X-Admin-Token: <token> header.

If the new configuration is invalid, the server keeps running with the previous configuration and logs the error.

Content Validation Warnings

Accent CMS validates content automatically when pages are loaded. Each validation check and its resolution is listed below.

Running Validation

# Validate all content
accent validate

# Validate with a specific config file
accent validate --config prod.yaml

# Use in CI (exits with code 1 if problems found)
accent validate || echo "Content issues found"

The output groups issues by page with severity labels:

Content Validation Report
=========================

Warnings (2):
  /blog/old-post
    - Missing template: "legacy-layout" not found in current theme
    - Invalid date: "2024-13-01" is not a valid date

Info (1):
  /docs/guide/setup
    - Orphaned page: parent "/docs/guide" is not published

Summary: 0 errors, 2 warnings, 1 info across 3 pages

Validation is advisory: issues are reported but do not block page serving. The one exception is unparseable frontmatter – a page whose frontmatter does not parse cannot be loaded at all, so it is absent from serve and build output until fixed. The server and the build log a warning naming the file, and accent validate reports it as an error.

Performance Issues

General Performance Tips

• Use accent serve --production for optimized caching behavior.
• Monitor server memory usage and adjust media.cache.max_size_mb accordingly.
• Use accent build for static output if content does not change frequently.
• For sites with thousands of pages, pagination reduces per-request work.
• Keep images at reasonable sizes. Accent CMS processes them on demand, so very large source images increase first-request latency.

Server Seems to Stall After Being Left Idle

If you come back to a laptop after a break – or reconnect after switching networks – and the first page load hangs or the hot-reload browser refresh stops arriving, the cause is usually a connection the server still believes is open.

When a client disappears without closing its connection cleanly (the laptop slept, Wi-Fi power-save kicked in, the router re-assigned the NAT mapping, the browser tab crashed), no FIN packet ever reaches the server. Nothing in HTTP tells the server the peer is gone. Left to the operating system’s default retransmission timeout, the dead connection can occupy a slot for 16 minutes or more, and anything the server tries to write to it – a hot-reload event, for instance – stalls before eventually failing.

accent serve enables TCP keep-alive probes on both its HTTP and HTTPS listeners to close that window. A connection that goes quiet is probed after 60 seconds, re-probed every 10 seconds, and dropped after three unanswered probes – so a vanished client is cleaned up in roughly 90 seconds instead of a quarter of an hour. On HTTPS, where browsers negotiate HTTP/2, the server additionally sends an HTTP/2 PING every 30 seconds and closes the connection if it is not acknowledged within 10 seconds.

This is on by default and needs no configuration.

accent serve-static and accent docs serve bind their own listeners and do not yet enable keep-alive. If you hit an idle stall while previewing a static build or the embedded docs, the connection can linger for the operating system’s default timeout – 16 minutes or more – rather than 90 seconds. Reloading the page opens a fresh connection and clears it.

If a stall persists for more than a couple of minutes after a reload, it is not a stale connection – check the “Performance Issues” section above, and note that on macOS the operating system’s App Nap can throttle a backgrounded terminal running accent serve. Keeping the terminal window visible, or running the server under a process manager, avoids that.

Markdown Rendering Issues

Frontmatter Troubleshooting

The most common rendering problem is frontmatter appearing as plain text. The --- delimiter must be:

• On the very first line of the file (line 1, column 1)
• Exactly three hyphens with no trailing spaces
• Not preceded by a byte-order mark (BOM) or blank line

If you copy content from another system, check for invisible characters at the start of the file.

Plugin Errors Free

Plugin Debugging

# List installed plugins
accent plugin list

# Check plugin info
accent plugin info <name>

# Install a plugin
accent plugin install <url>

Plugins run in a sandboxed WASM environment with bounded fuel (computation steps). If a plugin exhausts its fuel, Accent CMS terminates it and logs the error. Increase the fuel limit in config.yaml if the plugin does legitimate heavy computation:

plugins:
  fuel_limit: 200000  # default: none (no limit)

Build Errors

Build Command Reference

# Basic static build
accent build --output ./public --base-url https://example.com

# Build with a specific config
accent build --config prod.yaml --output ./dist

# Dry run (validate without writing files)
accent build --output ./public --dry-run

Configuration Errors

Validating Configuration

Before deploying, verify your configuration loads correctly:

# The server will fail fast if config is invalid
accent serve --config prod.yaml

# Validate content with a specific config
accent validate --config prod.yaml

Common YAML mistakes:

• Incorrect indentation. YAML uses spaces, not tabs. Nested fields must be indented consistently.
• Unquoted special characters. Values containing :, #, [, ], {, } must be quoted.
• Boolean confusion. yes, no, true, false are booleans in YAML. Quote them if you mean a literal string.

Getting Help

When the sections above do not resolve your issue, use these resources.

Self-Service Debugging Tools

• Content validation: Run accent validate to scan all pages for common problems.
• Debug panel: Add ?acdbg to any page URL to inspect the full template context, page hierarchy, validation issues, custom frontmatter, config, search, and cache stats. Use ?acdbg=right or ?acdbg=float for alternative panel positions.
• Server logs: Check terminal output for error messages, warnings, and content loading details.
• Version info: Run accent --version to display the version, edition, and license status.

Asking and Reporting

If you have found a bug or need help with an issue not covered here:

1. Check the server logs and the debug panel for error details.
2. Note your Accent CMS version (accent --version).
3. Prepare a minimal reproduction if possible (a small config.yaml and content directory that triggers the problem).
4. Take it to the forum – the same three items make a question answerable as well as a bug actionable. File it on the issue tracker if you are confident it is a defect.

If the missing piece is a capability rather than a fix, check the Hub before building it: it is the signed registry of plugins, themes, and starter templates, and someone may already have published what you need.

Common Quick Fixes

HTTPS in dev mode

accent serve binds HTTPS with a self-signed certificate cached under your platform cache directory, so the browser warning appears on the first visit and not on every restart.

A wildcard bind (server.address: 0.0.0.0) is the case Accent cannot solve for you: it does not know which of the machine’s addresses a visitor will type, so the certificate covers only loopback and a phone or second machine gets ERR_CERT_COMMON_NAME_INVALID. The server warns about this at startup. Name the address explicitly:

ACCENTCMS_DEV_CERT_SANS=192.168.1.20 accent serve

Or drop back to cleartext with accent serve --no-tls.