GuideHelp

Troubleshooting

Check what a workflow needs with douze doctor, read Douze's errors, and fix the errors that come up most.

This page covers the tools that tell you what is wrong (douze doctor, the error format, verbose output, exit codes), then the errors that come up most, with their fixes.

Check the requirementsLink to this heading

Some steps need something outside Douze: libvips for the image steps, the .NET SDK for hover-csharp, Go for hover-go, the program a command step runs. Every build checks them before any unit runs, and fails at once when one is missing. douze doctor checks them all without building:

douze doctor
STEP        REQUIREMENT       STATUS    DETAILS
images      libvips           ok        8.18.7
typescript  typescript 7.0.2  download  is not installed: it is downloaded for osx-arm64 on first use, or now by 'douze tools install'
minify      esbuild           missing   is not on PATH: install esbuild and add its folder to PATH, or change the 'run' line of step 'minify'

1 requirement missing: builds fail until it is fixed

A requirement is ok, download (a tool Douze downloads on first use), missing, or unchecked when it is only known during the build (a run line that starts with a template). Douze runs nothing to check: a command's program is looked up on the PATH, or relative to the step's cwd when it is a path, and its version is not checked. doctor exits with 1 when a requirement is missing, so a CI job can run it first, and with 2 when douze.yml is invalid. It takes -s, -w and --cache-dir.

douze tools install downloads the tools that steps would download on first use (the TypeScript engine, the Roslyn language server, gopls, the tool of command steps) into <cache>/tools/, for an offline machine or a CI cache:

douze tools install --cache-dir .cache/douze

Read an errorLink to this heading

A build error names the step, the file and, when it is known, the line and column:

error: render: /docs/a.md(12,3): Unknown tag 'tabss'; did you mean 'tabs'?

The path is the file's path in the site at that step: after the permalink step, docs/a.md is /docs/a/index.md. An error in a shortcode names the shortcode and the page. Errors of douze.yml name its line and column, and stop the build before it starts, with exit code 2:

douze.yml(3,3): error: step 'render' needs unknown step 'pagse'; did you mean 'pages'?
douze.yml(4,3): error: unknown built-in step 'writ'; did you mean 'write'?

By default, a failing step stops, the steps that need it are skipped, and the other steps finish, so you see every error of the build. --keep-going makes the failing step process its other files too. --fail-fast stops everything on the first error.

-v (--verbose) adds stack traces, a line per unit in the plain view, and the output of batch commands, whose working folders under .douze/tmp/ it keeps. --print-workflow prints the workflow the build runs, the default steps included, to check what a douze.yml really does.

Exit codesLink to this heading

Code Meaning
0 the build succeeded
1 the build has errors, or a requirement is missing
2 invalid command line or workflow file
130 the build was cancelled with Ctrl+C

Common errorsLink to this heading

Unknown step or fieldLink to this heading

douze.yml(3,41): error: unknown field 'if' on step 'render'
douze.yml(4,3): error: unknown built-in step 'writ'; did you mean 'write'?

uses takes the name of a built-in step (see the list of steps), and a step takes only the fields of the configuration reference. Option names under with are checked the same way.

Unknown toolLink to this heading

douze.yml(3,63): error: unknown tool 'pagefnd' on step 'search'; Douze knows 'lightningcss' or 'pagefind'

tool takes the name of a tool Douze downloads, optionally with a version (pagefind@1.5.2). Any other program goes in the run line, without tool. See Command steps.

Unknown variableLink to this heading

error: unknown variable 'og' in environment variable 'DOUZE_VARS__og'; declare it in 'vars'

A DOUZE_VARS__<name> environment variable, --var or --env sets a variable that the vars section of douze.yml does not declare. Declare it, or unset the environment variable: one left in the shell applies to every site you build there. See Environment variables.

A command is not on the PATHLink to this heading

error: minify: esbuild is not on PATH: install esbuild and add its folder to PATH, or change the 'run' line of step 'minify'

Install the program, or start the run line with its path. On Windows, run npx and other .cmd scripts through the shell (the default, shell: true). A tool that Douze can download, such as Pagefind, can use tool: instead and needs nothing installed (see Command steps).

error: twins: /docs/a.md: the permalink of step 'twins' is '/docs/.md' for '/docs/a.md': it has an empty file name, a value of the template is probably undefined

The permalink of a fork step reads a value that the file does not define. Fix the name, or set strict: true on the step to get undefined variable '<name>' instead.

Liquid in Markdown textLink to this heading

error: render: /docs/a/index.md(1,26): Invalid 'if' tag

A Markdown page is a Liquid template, and only its fenced code blocks are protected. Liquid syntax in inline code or in text runs. Wrap it in {% raw %}...{% endraw %}, or set liquid: false in the page's front matter, or in its folder's data file for a whole folder. See Markdown.

An undefined variable shows nothingLink to this heading

An undefined variable renders as nothing, and so does an unknown filter: {{ "x" | nosuchfilter }} renders x. To catch typos in variable names, set strict: true on the liquid step:

render:
  needs: paginate
  uses: liquid
  with:
    strict: true
error: render: /index.md: undefined variable 'nme'

strict does not catch unknown filters. Check filter names against the Liquid reference.

Invalid front matterLink to this heading

error: pages: /index.md: (Lin: 1, Col: 0, Chr: 12) - (Lin: 1, Col: 0, Chr: 12): While parsing a flow sequence, did not find expected ',' or ']'.

The YAML of the front matter does not parse; the position is inside the front matter. Quote values that start with [, {, * or &, or that contain :.

Two files have the same outputLink to this heading

error: write: /index.html: output '/index.html' is produced by both '/_content/index.html' and '/_content/index.md'

Two sources resolve to the same path: index.md and index.html in one folder, or two permalinks that collide. Rename one, or set its permalink.

A JSON or YAML file is not publishedLink to this heading

In the default workflow, every .json, .yml, .yaml and .xml file of the content folder is folder data, read and not copied. Name a published JSON file name.json.liquid, or put it in a folder that the default inputs do not read. See Data files.

A code sample fails the buildLink to this heading

A fence that a hover step checks has a compile error. Fix the sample, or list the expected error (// @errors: 2322 in TypeScript), or set errors: warn on the step. See Code hovers.

The cache is used by another buildLink to this heading

warning: the cache '.../.douze/cache' is used by another build: building without it

A douze serve or douze watch session holds the cache. The build works, without it. Stop the session, or pass another --cache-dir.

Fontconfig error on macOSLink to this heading

Fontconfig error: Cannot load default config file: File not found

Pango prints this when a social-image step lays out text on a machine without a Fontconfig configuration. On macOS douze configures Fontconfig itself when neither FONTCONFIG_FILE nor FONTCONFIG_PATH is set and /usr/local/etc/fonts/fonts.conf (an Intel Homebrew install) does not exist: it writes a configuration of the macOS font folders to a douze-fontconfig folder of the temporary folder. If you still see the message, one of those points to a configuration that cannot be read. Either way the build succeeds; set fontfile on each text block so that the fonts do not depend on the system.

Still stuckLink to this heading

Build again with -v --plain --no-cache and look at the first error. If you found a bug in Douze, open an issue at github.com/sebastienros/douze with the command, the output and a small site that shows it.

See alsoLink to this heading

Esc to close