static_

Troubleshooting

Build errors

Errors show the file, the line and a code frame, in the terminal and as an overlay in static dev. Static stops on these rather than producing a broken page.

Unknown component <Foo>

The component is not in components/ (or the built-ins). Create components/Foo.vue, or check the spelling. Names are matched by file name converted to PascalCase.

Property "x" was accessed during render but is not defined

A template uses a variable that does not exist. Globals are site, data, env, page, navigation, collections, currentYear, dev, frontmatter keys and, on data pages, the as variable. In <script setup> get them from useStatic().

.html pages are no longer supported / old EJS templates/base.html

The project was written for the old EJS version. See Migrating from EJS.

Invalid frontmatter ... (quote values containing ":")

A frontmatter value contains a colon. Wrap it in quotes: description: "Fast: simple: static".

Duplicate slug

Two collection entries produce the same URL. Change one file name or its slug:.

Warnings from static check

warning fix
site.json has no "url" Set url to your production origin so canonicals, sitemap and RSS can be generated. A common pattern is "url": "${SITE_URL}" with SITE_URL in .env.
meta description is ... chars Aim for 40 to 160 characters per page.
duplicate title / duplicate meta description Give each page a unique title and description.
image ... has no alt text Add alt, or alt="" for decorative images.
broken link: /x The target page or file does not exist in the build.
0 or 2+ <h1> Use exactly one <h1> per page.

Dev server

  • Port in use: static dev picks the next free port and prints it. Set one with --port=4000.
  • A change does not appear: the dev server rebuilds on save; check the terminal for a build error. After an error, fix it and save again.
  • Styles missing: styles/main.css must contain @import "tailwindcss"; for Tailwind 4 processing.

Images

  • Only files in images/ (and a collection's media/) get optimised variants. Reference them without a leading path: <Image src="photo.jpg" />.
  • Files in public/ are copied unchanged and are not resized.

Deploys

  • Nothing deployed: static deploy stops when the build fails. Fix the error printed above it.
  • Cloudflare asks to log in: set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID in .env.local or the environment.
  • deploy.project missing: Cloudflare deploys need "deploy": { "target": "cloudflare", "project": "<name>" } in data/site.json.
  • CI cannot find static: the workflow installs the CLI from the spec in its install step. Point it at a location your CI can reach.

Still stuck?

Run static check for the full list of warnings, and static build to see the complete error with its code frame.