--- title: "Gotchas" space: "Commera" url: "https://docs.bwh.tech/commera/theme-reference/gotchas" updated: "2026-10-08" --- 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 `.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//.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//themes/...` returns 404, and the file exists | The bench has no link to your app's `public` folder | Run `bench build --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 - [Architecture](/commera/theme-reference/architecture) - [Build a Commera theme](/commera/build-a-theme/overview)