Troubleshooting
Diagnose creator, AI, CMS and portal integration issues.
09 — Support and incident troubleshooting runbook
Symptom: Continue/Start is unresponsive
- Check the actual deployed `creator-v4.js` version and browser console errors.
- Confirm the DOM includes `.v4-root` and the clicked control has `data-v4-action`.
- Verify `/create/` has the `v4-creator-page` body class.
- Confirm legacy click handlers are not canceling events; creator controls use a scoped capturing click handler with default prevention and propagation isolation.
- Check form validation. Missing goal/name/email/consent should display an inline message rather than silently advance.
- Test mouse, touch and keyboard. Retest on an incognito browser to eliminate stale cache.
- Check whether a CMS refresh or SPA navigation is unexpectedly replacing `#main`; the current creator must not be wiped during form entry.
Symptom: Old Create your project visible under the wizard
- Inspect `#main` children and the active route; the page should contain only the mounted Creator V4 root for the creator view.
- Verify `body.v4-creator-page` CSS loaded and the creator's stylesheet has the newest version.
- Check `public/platform.js` old `createPage()` and any late-injected planner widgets.
- A stale script order can cause the older route renderer to win. See [Architecture](./02-ARCHITECTURE-AND-DATA-FLOW.md).
- Do not delete the old planner source blindly: other pages may still depend on it. Isolate it by route.
Symptom: Project AI button missing or unresponsive
- Confirm `creator-ai.js` was served, has no syntax errors, and `#v4-ai-slot` exists.
- It should mount at initial DOM ready, `studio:route`, or `veloryz:creator-render`.
- Examine overlay/z-index/pointer-events and left positioning on narrow screens.
- If panel opens but replies fail, inspect the POST to `/api/project-ai`; distinguish a frontend event problem from an unavailable inference provider.
- When provider unavailable, the client should show explicitly prewritten guidance, not an invented model reply.
Symptom: The wrong pricing or an unavailable promotion appears
- Check published `site.creatorPricing`, not just admin draft.
- Verify that category-specific amounts are numbers and that the current backend recognizes the category/pricing schema.
- Check whether the promotion is enabled, terms complete and expiry current.
- Confirm an offer is not being subtracted from the automatic estimate. Recompute in a new browser session if necessary.
Symptom: Enquiry reference missing
- Check browser Network response from `POST /api/enquiries`. A 2xx with `reference` is required for success.
- If 503, inspect the private database/backend, not the UI alone.
- Preserve the request UUID for retries; do not generate multiple unrelated references after a timeout unless necessary.
- If the server accepted a request but browser lost the response, ask the team to check the private inbox.
Symptom: Activation email not delivered
- First confirm the team actually created a private client workspace and generated an invitation.
- Check backend delivery status (accepted/manual/failed). Confirm `RESEND_API_KEY`, verified `PORTAL_FROM_EMAIL`, sender DNS records and recipient.
- Never show the client the API key or token hash.
- Distinguish project reference from invitation code.
- Do not promise delivery in twelve hours; escalate internally if a new enquiry remains untouched.
Incident severity examples
P1: cross-project data leak, unauthorized portal access, leaked provider key, payment/security issue — immediately disable affected access and escalate. P2: no one can submit a project / production endpoint down / all creator controls blocked — prioritize restore or rollback and display a safe contact alternative. P3: Project AI offline while creator is functional, noncritical layout issue — use labeled prewritten guidance and investigate provider/UX. P4: editorial typo, broken inspiration reference or documentation inconsistency — log, assign, fix in normal release.
Evidence to record
Timestamp, URL+query (without private tokens), browser version, screenshot with PII redacted, request status and error code, deployed commit SHA, reproduction steps, affected users (anonymized), mitigation and follow-up owner. Do not paste customer emails, private invite codes, production keys or full AI chat transcripts into public issues.
