Troubleshooting
Find the message you saw, then apply the fix. Every heading below is a message or a symptom from DocSprout itself. Run the commands from your project’s top-level folder.
Configuration
both docsprout.json and dockit.json exist
DocSprout refuses to choose between the canonical docs/docsprout.json and the pre-rebrand docs/dockit.json. Keep one of them:
git mv docs/dockit.json docs/docsprout.json # adopt the canonical name
git rm docs/dockit.json # when docsprout.json is already authoritativerequired when modern documentation configuration exists
A docs/layout.json exists without its identity file. Create docs/docsprout.json, or remove the layout if the project should use configuration-free discovery. See Configuration.
Unknown field '...'
The named field is not part of schema version 1. Fix the spelling or remove the field; the message suggests the closest supported name. The DocSprout rebrand did not rename any configuration field.
invalid JSON: ...
A configuration file has a syntax error: a missing comma, a trailing comma or an unquoted key. Compare the file with the complete examples in Configuration and fix the punctuation; DocSprout does not guess intent in malformed JSON.
field 'project.name' must be a non-empty string
Every docs/docsprout.json needs a project name. Add "project": {"name": "Your project"} or correct the existing value. See Project metadata and colours.
field 'theme.preset' must be one of ...
A value is misspelled or unsupported. Presets are blue, teal, ocean and purple; styles are classic, paper and midnight; content widths are compact, comfortable and wide. See Themes and Reading width.
... asset '...' does not exist or ... path is unsafe
banner, identity.logo and theme.custom_css must each point at a file that already exists inside the repository. Create the file first, then correct the path. See Add a home-page banner and Custom CSS.
navigation page '...' does not exist
layout.json lists a Markdown file that is not on disk. Create the file or correct its path.
unlisted Markdown document '...'
A Markdown file under docs/ is absent from the navigation. Add it to layout.json, or set "unlisted": "exclude" to keep drafts unpublished. See Pages, home page and navigation.
Build and output
Refusing to replace output directory ... it is not owned by DocSprout
The output directory was not generated by DocSprout. Choose another --output, or delete the directory yourself if it is disposable. DocSprout writes the .docsprout-site ownership marker and also recognises the pre-rebrand .dockit-fp-site marker, so older generated directories rebuild safely.
Generated route collision: ...
Two listed documents would overwrite the same published route, for example index.md and docs-index.md when another page is home, or names differing only by case. Rename or move one file.
Markdown: unsafe local link ...
A page links outside the repository, or uses an unsupported URL scheme. Correct the link or move the target inside README.md or docs/.
heading fragment errors
A link points at a heading anchor that does not exist on the target page. Correct the fragment or add the heading.
Markdown content
Markdown: unclosed fenced code block or unclosed display math block
A fenced block opened with `` or $$` at the end of the block.
Markdown: unsupported admonition '...'
Only [!NOTE], [!TIP], [!IMPORTANT] and [!WARNING] callouts are supported. Correct the label or write an ordinary blockquote.
GitHub Pages
github-pages: this folder is not a Git repository
Run the command from the repository root, or create the repository first with git init.
<path> is not managed by DocSprout
DocSprout never overwrites a workflow it does not own. Keep your workflow and remove the managed path, or move your workflow aside and rerun docsprout github-pages.
Both .github/workflows/docsprout-pages.yml and .github/workflows/dockit-pages.yml exist
DocSprout refuses to run two deployment workflows. Keep the canonical docsprout-pages.yml, delete the pre-rebrand dockit-pages.yml, then run docsprout github-pages --update.
docsprout-pages.yml does not exist. Run 'docsprout github-pages' first
--update only refreshes a recognised managed workflow. Run the plain command once before using --update.
... is managed by DocSprout but uses vX
A managed workflow pins an older release. Update it deliberately:
docsprout github-pages --updateRelease history
invalid version manifest or field 'schema_version' must be 1
docs/versions.json is malformed or missing required fields. It needs schema_version: 1, a current release, and a non-empty versions list that includes current with unique releases and source refs. Compare it with Create the version manifest.
source_ref ... does not exist. Create the tag
docs/versions.json names a tag that is not present locally. Create and push the tag, or correct source_ref. See the pre-publish checklist.
current release ... does not match HEAD
The current release entry must point at the checked-out commit when you run check-release or build-all. Check out the release commit, or create the tag on the current one.
Documentation differs from HEAD. Commit docs changes...
Commit the documentation before publishing the current release; historical publication is always built from committed tags.
Local preview
serve: port must be between 1 and 65535
Choose a valid port, for example docsprout serve --port 8080.
the preview address is already in use
Another process owns the port. Choose another one with docsprout serve --port 8080.
ERROR: docs directory is missing from doctor
There is nothing to document yet. Run docsprout init, or create docs/ with Markdown. See Your first DocSprout site.