Troubleshooting (vibe coding)

See the troubleshooting hub for a combined decision tree across React and vibe-coding paths.

Quick decision tree

Symptom

Try this first

AI prompt

Blank dev page

Browser console errors

“Fix runtime errors in App.tsx without removing Course/Lesson structure”

Quiz won’t complete

ID + exact answer string

“Align checkId in App.tsx with lessonkit.json assessments[]”

LMS no completion

Bridge + allowlist

“Set lxpack bridge auto and allowedParentOrigins for staging LMS”

Package failed

IDs + layout

“Fix lessonkit.json ID parity; use single-spa layout”

Node errors

Version check

“Use Node 20.19+; rerun lessonkit package”

Full runbooks: React troubleshooting (decision tree + sections).

lessonkit: command not found

Use:

npx @lessonkit/cli dev

Or install globally: npm install -g @lessonkit/cli.

npm run dev opens but the page is blank

Ask the AI:

The Vite dev server runs but the page is blank. Check src/main.tsx and src/App.tsx
for runtime errors. Fix without removing Course/Lesson structure.

Open the browser developer console (F12) and paste errors into the chat.

Quiz does not mark complete

  • Confirm checkId on <Quiz /> matches lessonkit.json → course.assessments[].checkId

  • Confirm the learner selected the exact answer string from choices

LMS does not record completion after SCORM upload

Set lxpack: { bridge: "auto", allowedParentOrigins: ["https://your-lms.example"] } in src/courseConfig.ts before npm run build and packaging. Production requires the allowlist. Details: React troubleshooting — SCORM completion.

Packaging says layout not supported

Use "layout": "single-spa" in lessonkit.json. per-lesson-spa is not supported by lessonkit package (1.x).

“Could not find lessonkit.json”

Run commands from the project root (where lessonkit.json lives), not a parent folder.

AI changed IDs and tracking looks wrong

This is the most common packaging failure on the vibe-coding path. LessonKit requires ID parity between React props and lessonkit.json.

ID parity checklist

  1. Open lessonkit.json and note:

    • course.courseId

    • every course.lessons[].id

    • every course.assessments[].checkId

  2. Open src/App.tsx (and any block files the AI edited) and align:

    • <Course courseId="…">

    • <Lesson lessonId="…">

    • <Quiz checkId="…"> / other assessment blocks

  3. Re-run npm run build then npx lessonkit package --target scorm12

AI prompt:

Align courseId, every lessonId, and every checkId in src/App.tsx with lessonkit.json.
Do not rename IDs unless you update both files in the same edit. Fix package parity errors.

If packaging still fails, paste the CLI error into the chat. Full reference: Keep React IDs in sync · React troubleshooting — ID parity.

Node version errors during package

Install Node per Prerequisites — decision table, then:

node -v   # should be v20.19+ for init; v18+ may work for package on existing projects
lessonkit package --target scorm12

See Prerequisites.

Still stuck?