Troubleshooting
Messages from the wptom command itself are in CLI errors and fixes.
Installing
Section titled “Installing”npm install fails or hangs. Check your internet connection, then run it again. If it
mentions permissions (EACCES), don’t use sudo: your Node.js installation is set up for
another user; reinstall Node.js from nodejs.org.
npm warn … install scripts / approve-scripts. Recent npm versions don’t run packages’
install scripts unless the project allows them. Templates list the ones they need in
package.json (allowScripts), so nothing to do; if npm asks about a package you added
yourself, check it and allow it with npm approve-scripts.
EBADENGINE or “requires Node >= 22”. Install the current LTS of
Node.js.
Running locally
Section titled “Running locally”Port 4321 is in use. Another npm run dev is still running (maybe in another terminal or
editor window). Stop it with Ctrl C, or use the address the command prints:
Astro picks the next free port by itself.
My change doesn’t show. Save the file (VS Code: Ctrl/⌘ S),
then reload the browser. Fonts and astro.config.mjs are read when the site starts: stop and
start npm run dev after changing them.
/keystatic is empty or “not found”. It only exists while npm run dev runs, unless you
connected it to GitHub for the live site (Keystatic).
A feature says it isn’t set up. That’s on purpose until you add its key: Turn on the features.
Building
Section titled “Building”npm run build stops with a message about a field. A required field is empty or has the
wrong format; the message names the file and the field. Fix it in the content editor.
Brand: the accent is too dark to see on the dark theme or Brand: no AA-safe … for this color. The accent or second color in Brand can’t be made readable in both themes. Pick a
lighter or more saturated color. Brand: "…" is not a hex color means a typo: colors look like
#6d4bff.
Images fail to build. A photo file is damaged or not an image. Replace it in the editor.
Publishing
Section titled “Publishing”The build works on my computer but fails on Vercel. Usually a key that’s in your .env
isn’t in Vercel’s Environment Variables, or a file you didn’t commit. Compare, push, and
redeploy (Deployments → … → Redeploy).
My changes aren’t online. Did you commit and push? git status lists uncommitted changes;
then git add ., git commit -m "…", git push.
The site shows the wrong address in search results or shares. Set your domain in
astro.config.mjs (const site = 'https://example.com'), commit and push.
Updating
Section titled “Updating”See Keep your site up to date: conflicts, undoing an update, and sites created without the CLI.
Still stuck?
Section titled “Still stuck?”Email tom@wptom.com with what you did, what you expected, and the full message (copy it from the terminal). Using an AI assistant? Give it the error and let it use the WPTom MCP server to look things up.