Troubleshooting
Start with node bin/template-sdk doctor (or menu option 7): it checks Node, the built-in storefront runtime, the demo data, the browser and the offline CDN copies.
| Symptom | Cause and fix |
|---|---|
| "This copy of the SDK is incomplete" | The runtime/ folder is missing: unzip the SDK again (keep all its folders together). |
| Products never appear | With several active stores the shopper must choose one first (the store chooser). Try the single-store demo data, or check that the store blocks ([data-sf-store-dependent], [data-sf-store-gate], [data-sf-store-pill]) are in index.html. |
| The page has no icons / jQuery errors | The preview could not reach the CDNs. Run node bin/template-sdk cdn fetch once while online, then use node sdk dev --offline. |
| My demo data file is rejected | The message names the file and the problem (invalid JSON, a product without a name, a product for an unknown store…). See the format. |
| A placeholder shows as {NAME} | Unknown names are left as text. See the list; store values are empty until a store is chosen. |
| My <script> / onclick does nothing | Removed by the sanitizer. Use script.js. |
| Background image missing | Use url(/image/…) in CSS; relative URLs are not rewritten. |
| scroll-behavior has no effect | The CSS sanitizer removes it (see CSS). |
| Tests skip the browser suite | No Chrome/Edge/Chromium was found. Install one; Playwright's Chromium is detected too. |
| Port in use | The Studio and preview pick the next free port; pass --port to choose. |
| Edits made in another editor | The Studio watches the folder and reloads changed files; with unsaved edits in the Studio it asks which version to keep. |
| Package rejected by verify | Read the message: usually an install name the application does not accept, a missing template.json, or a file the application would not serve. |