Shop template troubleshooting

Start with the working walkthrough ZIP. If it uploads and your own design does not, compare the manifest and files first. Upload checking does not execute your JavaScript or prove the complete design works; test it in the draft shop.

Upload and file checks

Symptom	What to check
The ZIP is rejected immediately	Manifest at the ZIP root; no enclosing project folder; ordinary unencrypted ZIP; no PHP, build tools, source maps, .DS_Store or __MACOSX extras
The manifest is rejected	Exact format, numeric schemaVersion: 1, pages.home: "index.html", supported fields only, lowercase filenames, every named file present
HTML is rejected	No script/style/link/meta/base tags, embeds, SVG, inline styles/event handlers or forms. Inputs may only be search, checkbox or radio
CSS is rejected	No external URLs/fonts, @import, CSS escapes or image-set. Use a supported at-rule and safe local image paths
A picture fails	Actual JPEG/PNG/WebP bytes; supported extension; within 1 MB and four million pixels; no SVG or renamed unsupported format
A resource path fails	Relative lowercase filename; no spaces, URL, query string, .. or missing file. Paths are relative to the file using them
Size limit reached	Compress pictures, remove unused files and reduce scripts; check compressed, expanded and processed limits separately
Processing is busy	Wait briefly and retry. Avoid sending repeated simultaneous checks/imports
Upload allowance reached	Wait for the rolling 24-hour allowance. Repeated ZIP checks count; deleting templates does not reset it
A saved template cannot be removed	It is used by the draft, live shop or an assistant’s saved undo; replace or undo that use first

The overview lists the limits. A ZIP exporter may include directory entries in the archive’s entry limit; keep the archive small and avoid unnecessary folders. A template with several declared layouts repeats its processed styles, scripts and embedded pictures in each layout, so small source files can still exceed the processed-bundle limit.

Products or interactions do not appear

• Bottle is only available inside Bottle’s runtime, not when opening your file directly from disk.
• Put rendering inside Bottle.ready(function (data) { ... }). Make sure your HTML IDs match the JavaScript selectors.
• List the JavaScript file in scripts; don’t add a script tag to the HTML. Check the browser console for syntax errors or a null element access.
• The interface includes only public catalogue data. Check that the business has published the expected products and categories.
• A category view includes only its category’s products. Search includes only the supplied snapshot. Check catalogueTruncated before assuming data is missing.
• Description may be null, images may be empty, and content HTML may be empty. Guard those values instead of assuming they exist.

There is no customer/trade pricing snapshot, basket API, stock count, delivery estimate or secret API token in the template interface. Do not try to fetch private data to fill a gap.

Navigation does not work

Prevent default browser navigation for shop links and call Bottle.navigate with a supplied path. Do not invent product paths, add query strings or navigate directly through window.location.

Unknown routes, external URLs, API paths and unsupported account subpages are ignored. A literal #section anchor is different: leave it as normal same-document navigation. If you navigate the frame itself, Bottle may remove it and display its supported fallback layout.

Product details, basket, checkout, accounts and built-in information pages remain Bottle pages. That change in layout is intentional, not a broken custom template.

Draft and live shop differ

Applying a template changes the draft only. Use the editor’s draft preview to check it. Publish changes the live shop; Discard changes returns the draft to the published settings.

If a preview token expires, reopen the preview from the editor. Don’t copy tokens into template files or use another business’s preview URL. For a live shop immediately after publishing, allow a short cache refresh and try refreshing; public shop data may be cached for up to a minute. A changed draft template should appear on refreshing the draft preview without changing its URL.

Restore applies only the saved design, not a historical snapshot of all business data. Code templates preserve stored content sections; JSON colour-theme packs can replace homepage sections only after explicit confirmation.

Browser console messages

Open the browser developer tools in the draft preview. Select the /__theme/... frame when inspecting your template’s DOM and logs. Errors in your script are not always errors in the parent Bottle page.

Messages about blocked fetch, storage, remote resources, form submission or script execution can be expected when a template tries an unsupported operation. Fix the template; do not disable the sandbox or add secrets. An unexpected syntax error, missing DOM element or broken supplied navigation deserves investigation.

Debug with console.log of harmless public fields while developing; remove unnecessary logs before publishing. Never log or request tokens, credentials or customer data. After testing, check that no unexpected JavaScript errors remain on home, catalogue, category and supported content pages.

Layout is clipped, too tall or shifts

Let the document grow naturally. Avoid a fixed-height wrapper, a full-page nested scroll area, absolutely positioned main content, or height: 100vh on the whole template. Bottle measures the frame and clamps its height; extremely long pages should be shortened or split.

Reserve image space with supplied dimensions or an aspect ratio, and use object-fit: contain for product pictures. Let grid columns and text stack/wrap on phones. Check that [hidden] elements stay hidden even if your CSS gives them another display value.

Before asking for help

Include the template name, which step failed, the error text, browser/device and a minimal ZIP demonstrating the issue. Redact credentials, preview tokens, personal information and private business data. Link your designer to the reference rather than weakening security to get an incompatible project working.