Troubleshooting - Mattersimple

An upload (or push, or check) lists every problem at once. Here is what each one means.

The zip

Problem	Fix
The zip is larger than 20 MB.	Compress images, remove unused fonts and assets.
The file is not a valid zip archive.	Re-create the zip, or use `mattersimple-theme package`.
The zip has more than 500 files.	A theme can have at most 500 files (development files don't count). Combine or remove files.
The zip has too many files. Leave out node_modules…	Zip the theme without `node_modules/`, or use `mattersimple-theme package`.
The theme is larger than 40 MB once unpacked.	Make assets smaller.
“…”: unsafe file path.	Use only letters, digits, spaces and `_ . / @ ( ) + -` in names, with no `..`.
“…”: symbolic links aren't allowed.	Replace the link with the actual file.
“…”: larger than 5 MB.	Make that file smaller.
“…”: suspicious compression ratio.	The file compresses unusually well (often generated padding); re-export it.

Problem	Fix
`…: this file isn't allowed in a theme (wrong folder, name or type).`	Check the folder and name against Theme structure. Common causes: subfolders in `assets/`, capital letters in a section name, a `.php` or `.html` file.
`layout/theme.liquid is missing.` / `config/settings_schema.json is missing.`	Every theme needs these.
`templates/index.json is missing — every theme needs a home page.`	Add `templates/index.json` (or `index.liquid`).
`layout/theme.liquid must output {{ content_for_header }}` (or `content_for_layout`)	Add `{{ content_for_header }}` in `<head>` and `{{ content_for_layout }}` in `<body>`.
`screenshots/desktop.png (or .jpg/.webp) is missing`	Add a screenshot of your theme.
`…: must be at least 1600×1000 pixels` / `not a PNG, JPEG or WebP image` / `larger than 5 MB`	Export the screenshot again at the right size and format.

Problem	Fix
`…: invalid JSON (…)`	A JSON file doesn't parse: look for trailing commas and unquoted keys.
`…: the {% schema %} block isn't valid JSON.`	Same, inside a section's schema.
`config/settings_schema.json: group #N needs a “name” and a “settings” list.`	Each group is `{ "name": "…", "settings": [ … ] }`.
`…: unknown setting type “…”.`	See the setting types.
`…: every … setting needs a lowercase “id”.`	Ids use `a-z`, `0-9` and `_`.
`…: the setting id “…” is used twice.`	Ids must be unique within a schema (or a block).
`…: the select setting “…” needs “options”.`	Add `"options": [{ "value": "…", "label": "…" }]`.
`…: every block in the schema needs a “type”.`	Give each block in `blocks` a `type`.
`…: “animations” must be true or false.`	A section's or block's `animations` key turns the platform's animation settings off with `false`. Leave it out, or use `true` or `false` (not a string). See Platform settings.

Problem	Fix
`sections/x.liquid (line N): …`	A Liquid syntax error: an unclosed tag, an unknown tag, a missing `endif`…
`templates/x.json: section “…” uses the unknown type “…”.`	The template names a section that's in neither your theme nor the Counsel theme. Add `sections/<type>.liquid` or fix the `type`.

My CSS change doesn't show. Run npm run build:css (dev does it for you), and check the class is written in full in a .liquid file (Styling).
A script or font doesn't load. The browser console shows what the content security policy blocked.
A section or block doesn't animate. Check the theme's Motion setting isn't Off and your device doesn't ask for reduced motion. A block needs {{ block.theme_attributes }} on its element, and a repeated item needs data-animate-item. In the theme editor, animations only play when the effect changes; view the site itself to see them on scroll (Motion and animations).
A section shows a red box in the theme editor. It's that section's Liquid error; visitors don't see the box.
push says “This is the live theme”. Add --allow-live, or push to an unpublished copy and publish it.
401 from the CLI. The token expired or was revoked: create a new one and run login again.