Troubleshooting

Solve common issues with Content Mode: content not appearing, template errors, relation problems, and build issues.

Content Not Appearing

If your content isn't showing up in the build output, check these common issues:

Content Mode Not Enabled

Problem: Content files exist but aren't being processed.

Solution: Verify Content Mode is enabled in Site Settings → Build Settings. The "Enable Content Mode" toggle should be on.

Missing Configuration

Problem: content.config.json doesn't exist or is invalid.

Solution: Ensure content.config.json exists in your project root and contains valid JSON. Check for syntax errors.

Content Not Published

Problem: Content files exist but aren't included in builds.

Solution: Check the published field in your content's front matter. It should be true or omitted (defaults to true). If it's false, the content won't be included.

Wrong Collection Directory

Problem: Content files are in the wrong location.

Solution: Verify files are in the directory specified by the path setting in your collection configuration. For example, if your config says "path": "content/posts", files should be in that exact directory.

File Format Mismatch

Problem: File format doesn't match collection configuration.

Solution: Check the format setting in your collection config. If it's set to "md", files should be Markdown. If it's "yaml", files should be YAML.

Template Not Rendering

If templates aren't rendering correctly, check these issues:

Template File Missing

Problem: Template file doesn't exist.

Solution: Verify the template file exists at the path specified in your collection configuration. Check the template setting matches the actual file location.

Incorrect Template Path

Problem: Template path in config doesn't match actual file location.

Solution: Ensure the template path in your collection config is correct and relative to your project root. For example, "templates/post.html" should point to a file at that location.

Template Syntax Errors

Problem: Template has syntax errors in Hammer tags.

Solution: Check your template for:

  • Properly closed tags (e.g., @if with @endif)
  • Correct variable syntax ($doc.title not doc.title)
  • Valid expression syntax

Build Log Errors

Problem: Template errors aren't obvious.

Solution: Check the build log for specific error messages. Hammer will report template errors with file paths and line numbers to help you locate issues.

Relations Not Working

If relations aren't resolving correctly, verify these settings:

Relation Not Defined

Problem: Relation field isn't defined in collection configuration.

Solution: Ensure the relation field is properly defined in your collection's fields with "type": "relation", "collection", and "valueField".

Incorrect Reference Format

Problem: Relation reference format is wrong.

Solution: Relations should be referenced as "collection-name/slug". For example, "authors/john" not "john" or "authors:john".

Referenced Content Missing

Problem: The content being referenced doesn't exist.

Solution: Verify the referenced content file exists and has the correct slug. Check that the collection name matches exactly.

Collection Name Mismatch

Problem: Collection name in relation config doesn't match actual collection.

Solution: Ensure the "collection" value in your relation field definition exactly matches the collection name in your config.

Build Errors

If builds are failing, check these common issues:

Invalid JSON Syntax

Problem: content.config.json has syntax errors.

Solution: Validate your JSON syntax. Common issues:

  • Missing commas between properties
  • Trailing commas
  • Unclosed brackets or braces
  • Unquoted keys (JSON requires quotes)

Use a JSON validator or your editor's JSON validation to check for errors.

Missing Required Fields

Problem: Content files are missing required fields.

Solution: Check your collection's field definitions. Required fields must be present in content files. Review build warnings for specific missing fields.

Incorrect File Paths

Problem: File paths in configuration are incorrect.

Solution: Verify all paths in your configuration:

  • Collection path directories exist
  • Template files exist at specified paths
  • Paths are relative to project root

Build Log Review

Problem: Build fails with unclear error.

Solution: Review the build log for specific error messages. Hammer provides detailed error information including:

  • File paths where errors occur
  • Error types and descriptions
  • Line numbers when applicable

Publishing Issues

If content publishing isn't working as expected:

Published Field Value

Problem: Content marked as published isn't appearing.

Solution: Verify the published field value. It should be true (boolean) or omitted (defaults to true). String values like "true" won't work.

Scheduled Date Format

Problem: Scheduled content isn't publishing.

Solution: Check scheduledDate format. It must be ISO 8601 format (e.g., "2024-12-25T09:00:00Z"). Verify the date has actually passed for auto-publishing.

Scheduled Date Not Passed

Problem: Scheduled content with future date isn't appearing.

Solution: This is expected behavior. Scheduled content with future dates is excluded from builds. It will automatically publish when the date passes on the next build.

Content in Wrong Collection

Problem: Published content isn't appearing in collection loops.

Solution: Verify the content is in the correct collection directory and that the collection name in your template matches the config.

General Debugging Tips

Use these strategies to debug Content Mode issues:

Check Build Logs

Always review build logs for warnings and errors. Hammer provides detailed information about what's happening during the build process.

Validate Configuration

Use a JSON validator to ensure content.config.json is valid. Many editors provide JSON validation.

Verify File Structure

Ensure your directory structure matches your configuration:

  • Content directories exist
  • Template files exist
  • File paths are correct

Test Incrementally

Start with a simple configuration and add complexity gradually. This makes it easier to identify where issues occur.

Check Content Files

Verify content files have:

  • Valid front matter (proper YAML syntax)
  • Required fields
  • Correct file format
  • Valid relation references

Next Steps

If you're still experiencing issues: