These are the problems that theme authors hit most often. Each row gives what you see, why it happens, and the fix.
Theme record and folders
| What you see |
Why |
Fix |
| The theme folders are in the Commera app, not in yours |
Module was left at its default, Shop Themes, at the first save. Commera makes the folders once, in the app of the module. |
Clear Is Standard, save, and delete the record. Commera then deletes the folders and the JSON file. Create the record again with Module set before you save. If the theme was standard when you deleted it, delete its folders and its <folder>.json file in the Commera app yourself, or bench migrate creates it again. |
| No folders were made at all |
Developer mode was off at the first save |
Turn on developer mode with bench --site your.site set-config developer_mode 1, then create the record again. |
No shop_theme/<folder>/<folder>.json in your app |
Is Standard is not ticked. Commera writes the record's JSON only for a standard theme. |
Tick Is Standard and save. |
The theme is missing on another site after bench migrate |
The record's JSON was not in the app that you installed |
Tick Is Standard, save, commit the JSON, and migrate again. |
| Theme Name is not on the saved form |
The theme name is the record's name. The form shows it as the title. |
No fix needed. The name in the title is the theme name. |
| Empty folders are missing after a Git clone |
Git does not keep empty folders |
No fix needed. Commera needs only the folders that hold files. |
Rendering
| What you see |
Why |
Fix |
| The home page of a child of Summer Theme fails with HTTP 500. Other pages work. |
shop_theme_config() reads the active theme's Theme Settings, not the parent's. Summer Theme's home sections need its settings. |
Set the child's Theme Settings to Summer Theme Settings. |
The page prints {{ app_name }} as text |
A macro was imported without context, so it cannot see the page variables |
Import it with context: {% from "components/macros/branding.html" import brand_logo with context %}. |
Your copy of a templates/... file has no effect |
Only components/... and pages/... paths go through the theme chain |
Import from a components/... path, or copy the page that uses the core file. Do not put the copy in your app's templates/ folder. That replaces Commera's file for every theme on the site. |
| A page shows the old theme, or a core page |
No theme in the chain has the file in Template Path, so Commera's core page serves the URL |
Check the file path against the Themed Routes row. |
/en/about returns "not found" with pages/about.html in your theme |
Dynamic pages include the language in the path |
Move the file to pages/en/about.html, and add pages/ar/about.html. Tick Enable Dynamic Pages. |
A controller fails with ImportError on a relative import |
Commera loads a controller from its file path, not as a module of your app |
Use absolute imports, such as from acme_theme.utils import .... |
| A page loses the layout's stylesheets |
The page filled the head block without {{ super() }} |
Start the page's head block with {{ super() }}. |
| An Alpine component on the page does nothing |
tojson writes double quotes, and they end a double-quoted x-data attribute |
Single-quote the attribute: x-data='{ ... }'. |
| The page has no meta tags or structured data |
The theme emptied the seo or json_ld block, or copied base.html without them |
Extend components/base.html and leave both blocks alone. |
| The header preview in the /commera dashboard also shows the footer, or the reverse, or shows neither |
The layout is not components/theme_layout.html, or it does not use the block names that the preview looks for |
Name the layout components/theme_layout.html. Put the header in {% block site_header %} and the footer in {% block site_footer %}. |
Styles and assets
| What you see |
Why |
Fix |
/assets/<app>/themes/... returns 404, and the file exists |
The bench has no link to your app's public folder |
Run bench build --app <app>. |
| A 404 for an asset under the active theme's URL |
No theme in the chain has the file. shop_theme_asset_url() returns the active theme's URL so that the 404 shows the theme name. |
Add the file to the public folder, or fix the path. |
| The "Item added" toast is a large unstyled shape under the footer |
The toast uses Tailwind classes, and a plain-CSS theme does not load them |
Load /assets/commera/css/tailwind.css in the layout's head block, before your CSS. |
| Headings are small and thin after you load Tailwind |
Tailwind resets heading styles |
Set h1, h2 and the other headings in your CSS. |
| The merchant's colour changes have no effect |
Your CSS sets an --ls-* variable |
Remove it. Read the --ls-* variables and use your own prefix for your own variables. |
| A Tailwind theme has classes from other themes in its CSS |
The Tailwind build ran from a folder above the theme |
cd into the theme folder, then run the build. |
| New Tailwind classes have no effect |
The Tailwind output is not part of bench build |
Run the theme's Tailwind build, and commit the output. |
Preview and activation
| What you see |
Why |
Fix |
?preview_theme= shows the live theme |
Developer mode is off, or the value is the folder name, not the theme name |
Turn on developer mode. Use the theme name with %20 for spaces, such as Acme%20Catalog. Letter case does not matter. |
| The preview jumps back to the live theme after a click |
The link replaced the query string and dropped preview_theme |
Build links from window.location.href and change only one parameter. |
| A new Active Theme or route row has no effect |
It was changed in the database, not through the form, so the cache was not cleared |
Save it from Desk or the dashboard, or run bench --site your.site clear-cache. |
Next steps
.webp)
