Errors and fixes
Verso’s errors are written as sentences and say where to look. This page lists the ones you are most likely to meet, with the fix for each.
In the terminal, an error starts with the file and line, then says what’s wrong, then what to do:
× content/docs/reference/cli/page.json
This page uses the template "docs", but templates/docs.html doesn't exist. Templates: doc, docs-group, docs-home, home.
In the editor, the same messages appear in the problem panel at the top right. Publish refuses while any are left, and says how many.
A few messages are warnings, not errors. A build prints them and carries on, and Publish goes ahead. The common one is content left over from a field a template no longer has.
Starting and finding the site
| Message | What to do |
|---|---|
| This folder isn’t a Verso site, because there’s no verso.json here or above it. | Run the command in the site’s folder, or start a site with npx verso-cms new my-site |
| Elevate isn’t installed in this site yet. | Run npm install in the site folder, then try again. Verso sets up Elevate’s compiler itself once the package is there |
| Elevate isn’t set up in this site, so there’s no CSS to build. | Run npx elevate-framework prepare in the site folder |
| This copy of Elevate is too old for Verso. Verso needs Elevate 1.2 or later. | Run npm install elevate-framework@latest, then npx elevate-framework prepare |
| … already has files in it. Pick a new folder name, so nothing gets overwritten. | verso new only uses a new or empty folder |
| --… isn’t a Verso option. | Run verso --help to see the options |
Files and pages
| Message | What to do |
|---|---|
| This file isn’t valid JSON, so Verso can’t read it. | Look for a missing comma or quote near the line it names |
| This page doesn’t say which template it uses. | Add "template": "page", or the name of another file in templates/ |
| This page uses the template “…”, but templates/….html doesn’t exist. | Fix the name; the message lists the templates there are |
| … has content for “…”, but … no longer has that field, so it isn’t shown. | A warning. Remove it in Page settings, or put the field back in the template |
| “…” is rich text, so it belongs in ….html next to page.json. | Move the value out of page.json into its own file |
| “…” on … is required, but it’s empty. | Fill it in on the page, or remove :required at the line named |
| The image for “…” on …, …, is missing from the page’s folder. | Choose the image again in the editor |
| The date “…” should look like 2026-11-16. | Write dates as YYYY-MM-DD |
| There are no pages yet. | Add a folder to content/ with a page.json in it |
Templates
| Message | What to do |
|---|---|
| Template tags can’t go inside <script>. | Put the value in a data- attribute and read it from the script. See JavaScript |
| … can’t go inside a tag. Put it between elements. | Lists and conditions wrap elements; they can’t sit in an attribute |
| A rich text field needs an element to itself, like <div>{{ body:rich }}</div>. | Give the field its own wrapper with nothing else inside |
| An image field goes in an attribute, like <img src=“{{ photo:image }}”>. | Move it into src |
| Fields can’t go inside a list. | Use {{ item.name }} to show each listed page’s field |
| Lists go three deep at most. | Move the innermost list out, or show its pages another way |
| “…” isn’t something a list understands. | After the folder, use a sort, a number, skip-1, paged, tagged-…, has-…, no-… or name=value |
| Say how many go on each page, like {{ each:journal:10:paged }}. | Add a number before paged |
| Only one list on a page can be split into pages… | Keep paged on one list, the outermost |
| {{ paging.next }} needs a list split into pages… | Add paged to a list, or remove the paging. reference |
| {{ else }} goes inside {{ if }} or {{ each }}, before its closing tag. | Move it inside a condition or list |
| There’s already an {{ else }} for … | Each if or each takes one else |
| “…” isn’t a format. | Dates take long, short, numeric, month, year, iso; text takes words-20 or chars-120 |
| Verso only looks one level up… | Use parent.; there’s no parent.parent |
| A field that’s the same on every page can be text, rich text or blocks, not image. | Use a page field for images and colours, or put a shared image in a block in a shared block area, like {{ site.header:blocks }} |
| A block area needs an element to itself, like <div>{{ sections:blocks }}</div>. | Give the block area its own wrapper with nothing else inside |
| A block area can’t be required. | Remove :required from the blocks field |
| The block area “…” allows a block called “…”, but blocks/….html doesn’t exist. | Make the block, or fix the name after blocks: |
| {{ list:… }} can’t go inside {{ each:… }}. | A repeater can’t sit in a list of pages or another repeater. Move it out |
| {{ list:… }} needs an element to itself… | Wrap the repeater in its own element, like a <ul> |
| Each item in {{ list:… }} needs exactly one outer element… | Wrap each item in one element, like an <li> |
| There’s no part called “…” in parts/. | Make the file, or fix the name; the message lists the parts there are |
| Parts can’t include other parts. | Put both parts in the template instead |
| Parts can only be used in templates, not in blocks or other parts. | Copy what you need into the block |
| The part “…” shows part.…, but this {{ part:… }} doesn’t give it one. | Add the value, like title=item.title or title="…" |
| This page holds the tags of content/…/, but that folder doesn’t exist. | Fix "tags-of" in page.json, or remove it |
| … is never closed. Add {{ /each }} after the part it covers. | Close every each, if and list |
| This template lists the pages in content/…/, but that folder doesn’t exist. | Make the folder, or fix the name in {{ each }} |
| This template needs a <head>, so Verso can add the page title and stylesheet. | Start it with <!DOCTYPE html><html><head>… |
| A block needs exactly one outer element, like <section>…</section>. | Wrap the block in one element |
Classes
| Message | What to do |
|---|---|
| The class “pd:d99” isn’t valid. “pd” takes spacing tokens, and “d99” isn’t one | Use a token that exists. npm run elevate -- describe lists them |
| The class “is-open” isn’t valid. Unrecognized property “is-open” | Not an Elevate class. Use a data- attribute, start it with a dash, or add it to SafeList |
| Breakpoints out of order: /md/ comes after /lg/ in one class list | A note, not an error. Screen sizes are written smallest first, and a class after a marker applies from that size up. Move the classes so the sizes go in order; classes for every size go before the first marker |
| Breakpoint written twice: /md/ appears more than once | A note. Put that size’s classes together after one marker |
| Responsive ambiguity: the elements in … and … have exactly the same classes | A note. Two elements have the very same classes, written in a different order, so one uses a class on every screen and the other only from a size up. The browser can’t tell which is which. Add or change a class on one of them |
| “…” isn’t an element rich text can contain. | A key in "rich" in verso.json isn’t one of the allowed elements; the message lists them |
Publishing
| Message | What to do |
|---|---|
| Git isn’t installed on this computer, and Verso needs it to publish. | Install it from git-scm.com |
| This site isn’t a git repository yet, so there’s nowhere to publish. | Run git init in the site folder |
| Saved a restore point. To publish online, connect this folder to a GitHub repository. | Not an error: add a remote, and the next Publish pushes |
| Someone else published changes to … while you were editing. | Verso shows both versions side by side. Choose which to keep |
| Someone else changed the same site files (not just page content) while you were editing. | Your version is kept but not published. Combine the two in git |