Lettuce Docs Tags Graph

Publish failed

#docs#troubleshooting
~3 min read

Publish failed

Diagnosing build and deploy errors.

Build errors (lettuce publish)

By default lettuce publish writes the site to <vault>/_site. The vault is the first positional argument (or the current directory if omitted) — there is no --vault flag for publish.

A note publishes wrong (or not at all)

Malformed frontmatter doesn’t raise an error — Lettuce parses it leniently and just returns empty values for the block. So a note with broken YAML silently loses its frontmatter: if the published: key is the casualty it won’t publish at all; otherwise it publishes with default title/tags. There’s no “parse error” line to look for — if a note is missing or bare on the site, suspect its YAML.

Fix: Open the note and check the frontmatter. Common causes:

URL collision

Two filenames slug to the same URL.

✗ Two notes resolve to the same URL: /projects/lettuce/
  - Projects/Lettuce.md
  - Projects/lettuce.md

Fix: Rename one of the notes so they slug to distinct URLs.

out of disk

Build target is full.

Fix: Clear the output directory (<vault>/_site by default), free disk, retry.

Deploy errors (lettuce deploy)

Authentication failed (401)

GitHub PAT is wrong or expired.

Fix: Pass a fresh token via --token (or $GITHUB_TOKEN). Use a fine-grained PAT with Contents: Read/Write on the target repo. Tokens expire after 1 year by default — recreate annually.

Repository not found (404)

The PAT can see your other repos but not this one. Either:

Fix: Re-run lettuce deploy --repo owner/repo --token … with the right repo and a PAT that covers it.

branch protected

gh-pages (or whatever target branch) has GitHub branch protection rules disallowing force-push, which is how Lettuce’s deploy works.

Fix: Either disable force-push protection on gh-pages (use --branch to target a different branch name), or use a different branch and configure GitHub Pages to serve from it. Note that lettuce deploy builds to a fresh temporary directory and force-pushes that tree — it does not keep a checked-out site/ working copy you have to keep clean.

GitHub Pages says 404 after deploy

Deploy succeeded but the site isn’t visible.

Fix:

  1. Wait up to 60 seconds; Pages is eventually-consistent.

  2. Check Settings → Pages on the repo: source should be the gh-pages branch (or whatever you passed to --branch), root.

  3. HTTPS may take longer (15-30 minutes) the first time.

Pages: SSL certificate provisioning failed

Custom domain HTTPS issue. Pass the custom domain to lettuce deploy --base-url https://notes.example.com so the built links are absolute.

Fix: Set the CNAME DNS record to <user>.github.io. (note the trailing dot for FQDN); wait up to 24 hours; retry.