Troubleshooting
Fix the common failures in preview, check, screenshot and submission.
Port 7833 is busy
Symptom: the preview serves on a different port than you expected.
Cause: 7833 was taken, so the command picked the next free port up from it.
Fix: use the printed URL as-is. To pin a port instead, pass --port — but a pinned port is strict, and the command exits if that port is busy.
No browser found
Symptom: npm run screenshot exits with "No browser found".
Cause: it drives the preview with a Chromium-based browser, and none is installed.
Fix: install Google Chrome, or run npx playwright install chromium once. A custom executable goes in QUEEK_THEME_BROWSER.
The check's to-do list right after create
Symptom: a fresh theme fails npm run check with placeholder, description and screenshot findings.
Cause: the starter ships stand-ins on purpose — they are your to-do list, not faults.
Fix: replace the placeholder products and photos, write each template's description, and run npm run screenshot. The list shrinks as you finish each item.
[object Object] on the page
Symptom: a content section prints [object Object] instead of text.
Cause: renderMarkdown returns React elements, and they were passed to dangerouslySetInnerHTML, which expects a string.
Fix: render the elements as children — <div>{renderMarkdown(text, basePath)}</div> — or use <Markdown> from @usequeek/theme-kit/components/markdown.
A next/link import is rejected
Symptom: the check flags an import from next/link, next/navigation or next/image.
Cause: only the kit may know which framework runs the storefront.
Fix: import Link, useRouter and usePathname from @usequeek/theme-kit/navigation, and images from the kit's <Image />.
The preview says the store is not found
Symptom: a design URL renders a not-found page.
Cause: there is no demo store behind that URL — no demo.json for /default, or no demos/<id>.json for /<id>.
Fix: check the file exists and the design is declared in theme.config.ts under the same id.
The check passes but submission fails
Symptom: npm run check is clean, yet Queek rejects the theme.
Cause: five checks need Queek's side and never run locally: divergence from existing themes, the render probe, the price-range signal, demo art hosting and screenshot upload.
Fix: read what the rejection names — it is exact — and resubmit. See Submit your theme.