# How to Troubleshoot Hallmark Runtime Errors: A Complete Diagnostic Guide

> Troubleshoot Hallmark runtime errors by verifying file paths, checking reference names, and ensuring Node.js 14+ is installed. Resolve common issues with this diagnostic guide.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-26

---

**Most Hallmark runtime errors stem from incorrect skill installation, missing reference files, or invalid command syntax, and can be resolved by verifying file paths in the host's skill directory, checking reference names against the repository, and ensuring Node.js 14+ is installed.**

Hallmark is a **design skill** that runs inside Claude Code, Cursor, or Codex to audit and redesign web interfaces. When you encounter **hallmark runtime errors**, the issue typically traces back to one of three architectural layers: the Markdown skill definition in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md), the static reference library in `references/`, or the client-side JavaScript renderer in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js). This guide provides precise diagnostics using the actual source code from the `Nutlope/hallmark` repository.

## Verify Skill Installation and File Placement

Installation errors occur when the host LLM cannot locate the skill files or when the **front-matter** metadata is malformed.

### Check Directory Structure by Host

Each AI coding environment expects Hallmark files in a specific location. Verify your installation matches your host:

- **Claude Code**: `~/.claude/skills/hallmark/`
- **Cursor**: `.cursor/rules/hallmark.mdc`
- **Codex**: `~/.codex/skills/hallmark/` (or project-scoped)

If these directories are missing or empty, reinstall the skill:

```bash
npx skills add nutlope/hallmark

```

This command copies [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and the entire `references/` tree into the host's skill directory. Missing files trigger errors like *"cannot find …/SKILL.md"* or *"reference not found"*.

### Validate Front-Matter Syntax

Each copied file must begin with a valid front-matter block. Open [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) or any file in the skill directory and confirm it starts with exactly:

```markdown
---
applyTo: '**'
---

```

An invalid front-matter block prevents the host from loading the skill entirely, causing silent failures or parser errors at runtime.

## Validate Command Syntax and Arguments

**Command-syntax errors** happen when you omit required arguments or provide malformed paths to the `hallmark` CLI.

### Required Arguments for Each Verb

Hallmark exposes three primary verbs, each with mandatory targets:

```bash

# Score an existing codebase (no edits)

hallmark audit ./my-project

# Redesign a page while preserving copy/IA/brand

hallmark redesign ./my-page.html

# Extract DNA from a screenshot or URL

hallmark study https://example.com/hero

```

Omitting the target argument emits *"Missing required argument <target>"*. Supplying a non-existent path returns *"ENOENT: no such file or directory"*.

## Inspect the Reference Library

**Reference-lookup failures** occur when Hallmark cannot find static assets describing macro-structures, typography, motion, or genres.

### Resolve "Reference Not Found" Errors

If the error message reads **"Reference not found: macrostructures/…"**, perform these checks:

1. Open the referenced file in the repository, such as [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md).
2. Confirm the file is **not empty** and that heading names match the identifiers used in your command.
3. Verify the reference name is spelled exactly as it appears in the `references/genres/` folder (e.g., `modern-minimal` not `modern-minmal`).

The error trace typically points to `load.js:42` in the stack trace, indicating the exact line where the lookup failed.

### Verify Custom Theme Configuration

If using a custom theme, ensure [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) exists in the `references/` directory and that the macro-structure comment inside your generated HTML matches an entry defined in that file.

## Parse Error Output and Stack Traces

Hallmark prints concise stack traces that identify the offending layer. Examine the file path shown in the error:

```

Error: Reference not found: genres/modern-minimal
    at loadReference (/path/to/hallmark/.../load.js:42:15)

```

Cross-reference this path with the repository structure. If the file was renamed or moved, update the call site in your command or restore the original file from the repository.

## Enable Debug Mode for Deep Diagnostics

For cryptic failures, run the audit command with the `--debug` flag to print a **diagnostic dump**:

```bash
hallmark audit ./my-project --debug

```

The debug output reveals:
- Loaded skill files and their timestamps
- Resolved reference paths
- Front-matter parsing warnings

Scan this output to pinpoint exactly which layer—skill definition, reference lookup, or renderer—triggered the failure.

## Validate the JavaScript Runtime Environment

**Client-side JavaScript problems** arise when running the live demo or local previews, typically from outdated Node versions or corrupted builds in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).

### Node Version Requirements

Verify your environment meets the minimum version:

```bash
node --version   # Hallmark requires Node ≥14

```

### Rebuild Static Assets

If the browser console shows **"Uncaught SyntaxError"** or **"Cannot read property 'classList' of undefined"**, the CSS tokens in the built assets have likely drifted from the HTML markup. Rebuild the static files:

```bash
npm install       # Installs dev dependencies

npm run build     # Rebuilds assets from site/js/main.js

```

This regenerates the client-side renderer that drives the live demo and applies the *slop-test* gates.

## Reinstall the Skill as a Last Resort

If corruption persists across multiple files, wipe the skill directory and perform a clean installation:

```bash

# Remove existing copy (adjust path for your host)

rm -rf ~/.claude/skills/hallmark

# Re-install

npx skills add nutlope/hallmark

```

Because Hallmark consists of pure Markdown and static assets, a fresh copy guarantees no corrupted files remain from previous partial downloads.

## Summary

- **Verify installation paths** for Claude Code (`~/.claude/skills/hallmark/`), Cursor (`.cursor/rules/hallmark.mdc`), or Codex (`~/.codex/skills/hallmark/`).
- **Validate command syntax** by including required target arguments for `audit`, `redesign`, and `study` verbs.
- **Check reference files** in `skills/hallmark/references/` when encountering "Reference not found" errors.
- **Use `--debug`** to expose loaded files, resolved paths, and front-matter warnings.
- **Ensure Node.js ≥14** and run `npm run build` to fix client-side JavaScript errors in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).

## Frequently Asked Questions

### What causes "Reference not found" errors in Hallmark?

This error occurs when Hallmark cannot locate a file in the `references/` directory, such as [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) or a genre definition in `references/genres/`. Verify the file exists in the repository, check for exact spelling matches, and ensure the file is not empty. The stack trace typically points to `load.js:42` where the lookup failed.

### How do I fix front-matter parsing errors?

Front-matter errors happen when [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) or reference files lack the required YAML header. Open the offending file and confirm it begins with `---\napplyTo: '**'\n---`. Any syntax deviation, such as missing delimiters or incorrect indentation, prevents the host LLM from loading the skill.

### Where does Hallmark store its skill files?

The storage location depends on your AI coding environment. Claude Code uses `~/.claude/skills/hallmark/`, Cursor stores rules at `.cursor/rules/hallmark.mdc`, and Codex uses `~/.codex/skills/hallmark/`. If these directories are missing or contain corrupted files, reinstall with `npx skills add nutlope/hallmark`.

### Why does Hallmark report JavaScript errors in the browser?

Client-side errors like **"Cannot read property 'classList' of undefined"** indicate a mismatch between the built CSS tokens and HTML markup in the demo. Ensure you are running Node.js 14 or higher, then execute `npm install` and `npm run build` to regenerate the assets in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).