Troubleshooting

Installing

"command not found: hotdog-cms" (macOS, Linux) or "The term 'hotdog-cms' is not recognized" (Windows)

The terminal can't find the program. Check it's in a folder on your PATH: /usr/local/bin on Linux and macOS, or the folder you added on Windows. Close the terminal and open a new one, which picks up PATH changes. Then try hotdog-cms version. See Install.

"permission denied" when running it on Linux or macOS

It isn't marked as a program yet: run chmod +x on it, as in the install steps.

macOS says it "cannot be opened because the developer cannot be verified"

Choose Open Anyway in System Settings → Privacy & Security, or run xattr -d com.apple.quarantine /usr/local/bin/hotdog-cms. See Install on macOS.

The checksum says FAILED

The download was cut short or changed. Delete it and download it again. If it fails twice, tell us (see Getting help).

Building and previewing

"site.yaml: yaml: line 3: did not find expected key" (or a similar YAML message)

A line in site.yaml isn't laid out the way YAML expects, usually the spaces at its start. Look at the line it names and the one before. Lines that belong together start with the same number of spaces; use spaces, not tabs; put quotation marks around values containing : or #.

"field colour not found in type site.Config"

A setting HotDog doesn't know, often a typo. Check its spelling against the site.yaml reference. The same kind of message for a page means a mistake in its front matter.

"listen tcp 127.0.0.1:8140: bind: address already in use"

Something is already using that address, often another hotdog-cms serve in another terminal window. Stop it with Ctrl+C there, or use another port: hotdog-cms serve -addr 127.0.0.1:8141.

"hotdog-cms: usage: hotdog-cms new "

Options go before the folder: hotdog-cms new -name "My site" mysite.

"… and … both want /about/"

Two files would make the same address, such as content/about.md and content/about/_index.md. Rename or remove one.

My change doesn't show in the browser

Check the terminal running hotdog-cms serve: if your change has a mistake, it says so there, and the browser keeps the last good version. If not, reload the page.

Checks

"broken-link … links to /something/, which is not in the site"

A link on that page goes to an address with no page. Fix the link, add the page, or add a redirect. The page named is the one with the bad link, as its file in public/.

"image-location"

A photo still holds the place it was taken. Upload it through the editor, which removes it, or save a copy without location from your photo app.

Every rule is explained in What the checks mean.

The editor

"HOTDOG_EDITOR_SECRET must be set, at least 32 characters"

Set it in the same terminal before starting the editor. See Run the editor.

The platform says the redirect URL doesn't match

The sign-in app's redirect URL must be exactly your editor's address plus /auth/callback, such as http://127.0.0.1:8190/auth/callback. Open the editor at that same address (127.0.0.1, not localhost).

My site isn't in the list

With discover, a site needs a site.yaml with a url in it at the top of its default branch, and only GitHub, Gitea and Forgejo are searched. Or list it under sites: in editor.yaml.

I published, but the live site hasn't changed

Publishing in the editor updates your repository. The live site changes when your publishing runs: check your platform's pipeline, or the pull agent's log (journalctl -u site-publish). See Publishing.

Publishing

"… has files that hotdog-cms did not write; refusing to replace it"

HotDog only replaces a folder that's empty or that it wrote itself, so a wrong path can never wipe something else. Check the folder it names: for build, the -out folder; for a publish target, the path in publish.yaml. If it really is the right folder, holding an old site you want replaced, empty it once and try again.

Pictures or styles look old after publishing

Your browser, or a service like Cloudflare in front of your site, kept old copies. Pictures keep their names when they change, so a cache can hold on to them; give a changed picture a new file name, or clear the cache in your provider's dashboard.