Fix Common Build Errors

Diagnose and resolve the most frequent errors that come up when building a Great Docs site.

Most Great Docs builds complete without issues, but when something goes wrong the error messages can be cryptic, especially those originating from Quarto. This recipe covers the errors you are most likely to encounter and how to fix each one.

“quarto: command not found”

This means Quarto is not installed or not on your system PATH. Great Docs delegates all HTML rendering to Quarto, so it must be available as a command-line tool.

Install Quarto from https://quarto.org/docs/get-started/ and verify the installation:

quarto --version

If you installed Quarto but the command is still not found, check that the Quarto binary directory is included in your PATH environment variable. On macOS, the installer usually handles this, but on Linux you may need to add it manually.

“No module named …”

This error appears when Great Docs tries to import your package for introspection but the package is not installed in the current Python environment. Make sure your package is installed (in development mode if you are still iterating):

pip install -e .

If you are working in a virtual environment, confirm that you have activated it before running great-docs build.

“module key not set” or wrong module name

The module key in great-docs.yml must be the Python importable name, not the PyPI distribution name. For example, if you install a package with pip install py-shiny but import it as import shiny, the configuration should read:

module: shiny

Run python -c "import <module_name>" to verify that the name you are using actually works as an import.

Circular import or attribute errors during introspection

Some packages use lazy loading, conditional imports, or circular references that cause problems when Great Docs tries to introspect them at runtime. If you see tracebacks mentioning ImportError, AttributeError, or CircularImportError during the build, switch to static analysis:

dynamic: false

This tells Great Docs to use griffe-based static analysis instead of runtime introspection. Static analysis reads the source code directly and avoids triggering any import-time side effects.

YAML syntax errors

If you see an error like yaml.scanner.ScannerError or expected <block end>, there is a syntax problem in great-docs.yml. Common causes include:

  • Tabs instead of spaces (YAML requires spaces for indentation).
  • Missing quotes around values that contain special characters like colons or hash marks.
  • Incorrect nesting (a key that should be nested under a parent but is at the wrong indentation level).

A quick way to check is to paste the contents of great-docs.yml into an online YAML validator. Fix the syntax issue and rebuild.

“ERROR: FileNotFoundError” during Quarto render

This usually means a cross-reference or include directive points to a file that does not exist. Check the error message for the specific file path, then verify that the file is present at that location. Common causes:

  • A user guide page references an image that was not placed in the expected directory.
  • A cross-reference uses the source filename (like 07-deployment.qmd) instead of the output filename (deployment.qmd). In cross-references, use the name without the numeric prefix since Great Docs strips prefixes during the build.

Pages missing from the sidebar

If a page exists but does not appear in the sidebar, check the following:

For user guide pages, the file must have a numeric prefix (like 05-advanced.qmd) and be located in the user_guide/ directory. Great Docs discovers these files automatically based on their prefix.

For recipe or custom section pages, the file must be in the directory specified by the relevant entry in the sections list in great-docs.yml. The file name does not matter for discovery, but it does control sort order (files are listed alphabetically by path).

Build succeeds but the site looks wrong

If the build completes without errors but the output does not match your expectations, try a clean rebuild. Remove the great-docs/_site/ directory and run the build again:

rm -rf great-docs/_site
great-docs build

Stale files from a previous build can sometimes cause unexpected behavior, especially after renaming or deleting pages.

Still stuck?

If none of the above resolves your issue, the build output usually contains the relevant error message. Copy the full error text and search the Great Docs GitHub Issues to see if someone has encountered the same problem. If not, open a new issue with the error output, your great-docs.yml contents, and the versions of Great Docs, Quarto, and Python you are using.