# Fix Common Build Errors

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:

``` bash
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):

``` bash
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:

``` yaml
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:

``` yaml
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:

``` bash
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](https://github.com/posit-dev/great-docs/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.