---
title: Refusals and findings
description: Find the exact text of any message the tool prints, what causes it, how to fix it, and the exit code that comes with it.
slug: /reference/refusals
order: 2
visibility: public
redirects_from: []
---

# Refusals and findings

This page lists every line the tool can print about a problem, with its exact text, its cause, and its remedy. In the messages, `<...>` marks a value the tool fills in. The messages come in six groups:

- A usage error stops the tool before it runs.
- A refusal stops the build before it writes.
- An advisory finding is reported by the check, and the build still proceeds.
- A notice follows a successful build and leaves its exit code 0.
- A rendering failure stops the build before it writes.
- A publication failure can leave a backup folder behind.

A script that reads these messages should match the exit code, or a message's opening words up to its first dash. The words after the dash can change between versions.

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | The build wrote the tree, or the check found nothing. |
| 1 | The build refused or failed, or the check reported at least one finding. Read the message: a cleanup failure can occur after the new site is published. |
| 2 | The command line was wrong. The reason and the usage lines follow. |

## Usage errors

Exit code 2. The tool prints the reason on one line, then the three usage lines, and writes nothing.

The tool reads the source folder before it checks five of these errors: `build needs --out <dir>`, the base path, the origin, the exclusion prefix, and the corpus version. A missing or unreadable source folder therefore ends the run first, with a Node.js error and exit code 1.

| Message | Cause | Remedy |
| --- | --- | --- |
| `a mode and --source are required` | The first argument is not `build` or `check`, or `--source` is missing. | Write `tzdocs build --source <dir> --out <dir>` or `tzdocs check --source <dir>`. |
| `build needs --out <dir>` | A build without `--out`. | Give the output folder. |
| `--<name> needs a value` | A value flag is the last argument or is followed by another flag. | Give the value as the next argument. |
| `--<name> is given twice` | The flag appears twice. | Give it once. |
| `--<name> is not a flag the tool knows` | A misspelled or unknown flag. | Use a flag from the table on [Getting started](/getting-started/). The tool treats `--source=docs` as an unknown flag, so write `--source docs`. |
| `--base needs a path that starts with / and does not end with one, such as /docs, not "<value>"` | The value does not start with `/`, still ends with `/` after one trailing slash is removed, or has an unsafe segment. | Write the path the site is served under, such as `/docs`. |
| `--origin needs an http or https origin with no path, such as https://example.com, not "<value>"` | The value is not an `http` or `https` address, or it has a path after the host. | Write the address the site is served at, such as `https://example.com`. |
| `--full-text-exclude needs a tree-relative slug prefix such as /reference, not "<value>"` | The value is not a leading-slash path with safe segments. | Write the section's slug, such as `/reference`. |
| `--corpus-version needs a non-blank value` | The value is empty or whitespace. | Write the version text, or leave the flag out. |

## Refusals

Exit code 1. The build writes nothing. A source-level refusal is reported by the check as well, one per line. The build prints `the build refuses:` followed by one refusal per line, or one line beginning `the build refuses: `.

### Source-level refusals

| Message | Cause | Remedy |
| --- | --- | --- |
| `two files resolve to one slug <slug> — <file> and <file>` | Two files derive or declare the same slug, `guides/index.md` and `guides.md` for example. | Rename one file or change its `slug`. |
| `redirects_from <slug> on <file> collides with the live slug of <file>` | A `redirects_from` entry is a page's current slug. | Remove the entry, or rename the page it collides with. |
| `unsafe slug path "<slug>" on <file>` | The page's slug, declared or derived from its file name, breaks the [slug rules](/reference/page-source/#slug-rules): not a leading-slash path, or an unsafe segment such as a reserved device name. | Write a safe tree-relative slug, or rename the file. |
| `unsafe redirect path "<slug>" on <file>` | A `redirects_from` entry breaks the [slug rules](/reference/page-source/#slug-rules). | Write a safe tree-relative slug. |
| `unsafe route path "<route>" on <file>` | A slug or redirect that parsed is unsafe as a route. Only the build prints it, beside the `unsafe slug path` or `unsafe redirect path` line the check prints for the same route. | Write a safe tree-relative slug ([slug rules](/reference/page-source/#slug-rules)). |
| `duplicate redirect <slug> — <file> and <file>` | Two pages list the same old slug. | Keep the entry on the page the old address should reach. |
| `output path collision at <path> — <a> and <b>` | Two pages differ only in letter case, a page's file path is another page's folder, or a slug uses the name of a reserved root file. A copied file collides the same way: `guide/index.html` beside a page at `/guide`, or a file at the root named `docs.json` or another [reserved name](/reference/page-source/#path-collisions). | Rename one of the two, or move the page or the file off the reserved name. |
| `unsafe file path "<path>"` | A file beside the pages has a path that breaks the [slug rules](/reference/page-source/#slug-rules), a `#` in its name for example. | Rename the file. |
| `missing file in <file> — <href> resolves to <path>, which is no file beside the pages` | An image, or a link to a file with an extension other than `.md`, names a file the source folder does not have. A file in a folder whose name begins with a dot does not count. | Add the file, or correct the path. [Images and other files](/reference/page-source/#images-and-other-files) gives the resolution rules. |
| `missing file in <file> — <href> climbs above the source folder` | The reference's `..` segments lead out of the source folder. | Move the file into the source folder and link it from there. |
| `broken internal link in <file> — <href> resolves to <slug>, which matches no page or redirect` | A link points to a slug no page or redirect has. A link to a hidden page counts, unless the build or the check passes `--include-hidden`. | Correct the target, or add the redirect. |
| `reserved section title "<title>" at <file> — Start here and Optional are the index's own headings` | A top-level section's title, compared without regard to case, is `Start here` or `Optional`. | Retitle the section's index page. |
| `section index with a body at <file> — the build makes no page from the index of a section with entries; move its text to a page` | A folder's `index.md` has text after its front matter while the folder contains other pages or sections. | Move the text to a page of the section, and leave only front matter in the index. |
| `malformed front matter — <file>: <detail>` | The front matter does not parse. The detail is one of the lines in the next table. | Correct the named line against the [front-matter rules](/reference/page-source/#front-matter). |

The detail of a malformed front matter refusal:

| Detail | Cause |
| --- | --- |
| `front matter opens with --- and never closes` | No later line contains exactly `---`. |
| `front-matter line does not parse as key: value — "<line>"` | A metadata line is not `key: value`, or is indented. |
| `duplicate front-matter key — <key>` | The key appears twice. |
| `unknown front-matter key — <key>; a page takes title, description, slug, order, visibility, redirects_from, section` | A key other than `title`, `description`, `slug`, `order`, `visibility`, `redirects_from`, or `section`. |
| `order is not an exactly representable integer — "<value>"` | The order is not a decimal integer, or is outside -9007199254740991 through 9007199254740991. |
| `redirects_from not a one-line inline list — "<value>"` | The value is not `[ ... ]` on one line. |
| `redirects_from unclosed quote in list — "<value>"` | A quoted entry does not close. |
| `redirects_from empty list entry — "<value>"` | An entry between commas is empty. |
| `redirects_from invalid double-quoted text — "<value>"` | A double-quoted entry has an invalid escape or does not close. |
| `redirects_from invalid single-quoted text — "<value>"` | A single-quoted entry does not close, or has an undoubled apostrophe. |
| `redirects_from unsupported structured value; quote it to use literal text — "<value>"` | An entry starts with a structure character, a nested `[` for example. |
| `<key>: invalid double-quoted text — "<value>"` | A double-quoted value has an invalid escape or does not close. |
| `<key>: invalid single-quoted text — "<value>"` | A single-quoted value does not close, or has an undoubled apostrophe. |
| `<key>: unsupported structured value; quote it to use literal text — "<value>"` | The value starts with `[`, `{`, `\|`, `>`, `&`, `*`, `!`, or with `-` or `?` followed by whitespace. |
| `title is required and absent` | No `title` line, or an empty one. |
| `slug is not tree-relative (no leading /) — "<value>"` | A declared slug does not start with `/`. |

### The output folder

| Message | Cause | Remedy |
| --- | --- | --- |
| `output must be a directory, not a file or symbolic link — <path>` | `--out` points to a file, a symbolic link, or a junction. | Give a real folder, or a path that does not exist yet. |
| `output overlaps source — <out> and <dir>` | The output folder contains the source folder or sits inside it, a link included. | Keep the output folder outside the source tree. |
| `output contains an input source or asset — <path>` | A source file, the shell, the opening, or the stylesheet sits inside the output folder, by its given path or its resolved target. | Move the file out of the output folder. |

### The supplied files

| Message | Cause | Remedy |
| --- | --- | --- |
| `the shell file is absent at <path>`, `the home opening file is absent at <path>`, `the site stylesheet file is absent at <path>` | The flag points to a file that does not exist. | Correct the path. |
| `the shell lacks the marker <!--tzdoc:head-->`, `the shell lacks the marker <!--tzdoc:page-->` | The shell has no such comment. One line per missing marker. | Add the marker ([Style the site](/guides/style-the-site/), step 3). |

### The whole-text exclusion

| Message | Cause | Remedy |
| --- | --- | --- |
| `the excluded prefix "<value>" is not a route` | The prefix is not a safe tree-relative path. The command line reports this as a usage error first. | Write the section's slug. |
| `the excluded prefix <value> matches no page` | No page's slug equals the prefix or begins with it followed by `/`. | Correct the prefix, or leave the flag out. |

## Advisory findings

Exit code 1 from the check. The build proceeds, so a pipeline that must stop on one runs the check first.

### Links and slugs

| Message | Cause | Remedy |
| --- | --- | --- |
| `broken internal link in <file> — <href> matches no heading anchor on <file>` | The fragment matches no heading on the destination page. | Use an anchor from the manifest, or add the heading. |
| `broken internal link in <file> — <href> has malformed fragment encoding` | The fragment's percent encoding does not decode. | Correct the encoding. |
| `slug diverges from its folder path in <file> — slug <slug>, folder <folder>` | A declared slug puts the page in a folder other than its source folder, so the navigation and the address disagree. | Move the file, or drop the declared slug. |
| `section names no section of the corpus in <file> — <word>; the sections are <words>` | A declared `section` word is not the slug word of any top-level section. | Use a listed word, or drop the key. |

### Code fences

Each is reported as `code block in <file> — line <n>, fence "<info string>": <finding>`. The line is the opening fence's line. For a block nested inside a list or a block quote, it is the line the list or the quote starts on. The info string is written as a JSON string, so a double quote inside it appears as `\"` and a backslash as `\\`.

| Finding | Cause | Remedy |
| --- | --- | --- |
| `the language word "<word>" is not a name` | The word has a character outside letters, digits, and `_ + # . -`. | Use a name from the bundled set on [Highlight a code block](/guides/code-blocks/), or leave the language out. |
| `the title is given twice` | Two `title=` entries on one fence. | Keep one. |
| `the line set entry "<entry>" does not parse` | An entry in the braces is not a number or a range `a-b`, a negative number included. | Write numbers and ascending ranges, separated by commas. |
| `the line set entry "<entry>" is not a positive ascending range` | A zero, or a range whose second number is smaller than the first. | Count from 1 and write the smaller number first. |
| `the line set gives line <n>, past the block's last line, <m>` | The set lists a line the block does not have. | Remove the entry or shorten the range. |
| `the metadata "<text>" does not parse` | Text after the language word that is neither a title nor a line set. | Remove it, or rewrite it in the fence grammar. |
| `a mermaid diagram takes no title or line set` | A `mermaid` fence carries a title or a line set. A drawn diagram has no caption and no lines to emphasize. | Remove them from the fence line ([Add callouts and diagrams](/guides/callouts-and-diagrams/)). |

### Callouts

| Message | Cause | Remedy |
| --- | --- | --- |
| `unknown callout type in <file> — [!<word>] stays a block quote; the types are NOTE, TIP, IMPORTANT, WARNING, and CAUTION` | A block quote's first line is a bracketed word that is not one of the five callout markers. The quote renders as a block quote. | Use one of the five markers ([Page source](/reference/page-source/#callouts)), or reword the line. |

## Notices

Exit code 0. The build wrote the tree, and the notice follows the success line on standard error.

| Message | Cause | Remedy |
| --- | --- | --- |
| `notice: <N> pages hold mermaid diagrams, shown as code — run "npm install mermaid" in this folder to draw them.` | Pages hold `mermaid` blocks, and Mermaid is not installed where the build runs, so they show as code. The check prints no notice. | Run `npm install mermaid` in the folder where you run tzdocs, or pass `--diagrams-as-code` to keep them as code without the notice. |

## Rendering failures

Exit code 1, before anything is written to the output folder. The previous output is unchanged.

| Message | Cause | Remedy |
| --- | --- | --- |
| `the highlighter emitted markup the splitter does not know at offset <n>`, `the highlighter emitted markup the splitter does not know at the end` | For one code block's text and language, the bundled highlighter produced markup that the tool cannot split into lines. | Change that block's language word to `text` so that the build completes. |

## Publication failures

Exit code 1, after generation succeeded. [Output](/reference/output/#publication-and-recovery) describes the steps that produce these messages. A combined line, a failure followed by a cleanup part, begins with `Error: ` before the first message.

| Message | Cause | Remedy |
| --- | --- | --- |
| `output publication failed (<error>); restore failed (<error>); previous output remains at <backup>/previous` | The generated tree could not be renamed into place, and the previous output could not be renamed back. | Recover the previous output from the named folder before deleting anything. |
| A Node.js file-system error that mentions the rename | The generated tree could not be renamed into place, and the previous output was renamed back. | Correct the file-system condition, an open handle or a permission, and build again. |
| `new site is published; temporary backup cleanup failed at <path>: <error>` | The new site is in place, and the backup of the previous one could not be removed. | Remove the named folder. The output is current. |
| `new site is published; staging cleanup failed at <path>: <error>` | The new site is in place, and the temporary staging folder could not be removed. | Remove the named folder. The output is current. |
| Any message followed by `; staging cleanup failed at <path>: <error>` | A failure before publication, after which the staging folder could not be removed. | Read the first part as its own row. Remove the named folder. |
| Any message followed by `; temporary backup cleanup failed at <path>: <error>` | A failure before publication, after which the previous output was restored but the emptied backup folder could not be removed. | Read the first part as its own row. Remove the named folder. |