Troubleshooting

The problems people meet most often, and how to fix them.

"AUTH_SECRET is missing or too short"

Set AUTH_SECRET in .env to 16 characters or more (32 random characters recommended) and restart.

"Settings row missing: run npm run db:seed"

The database has tables but no data. Run npm run db:seed.

The seed says "Set ADMIN_PASSWORD (8+ characters)"

Set ADMIN_PASSWORD in .env. The seed refuses to create an admin with a weak or empty password.

I cannot sign in to the dashboard

  • Check the email in ADMIN_EMAIL: the admin is created only when the database has no dashboard account yet. If you changed the email after seeding, sign in with the old one, or delete prisma/maarifa.db and run npm run setup.
  • After 8 wrong passwords for one email, sign-in pauses for 15 minutes.
  • Behind HTTPS, check that SITE_URL starts with https://. Over plain HTTP in production the browser may drop the secure cookie.

An instructor sees "Your account is not linked to an instructor profile"

Open Dashboard > Admins, edit the account and choose its instructor profile. Instructors only manage the courses of that profile.

An instructor cannot publish a course

That is the default: the "Publish courses" permission is off for instructors. An admin publishes the course, or switches the permission on in Dashboard > Admin roles.

Card payment is not offered at checkout

All three are needed: the switch in Dashboard > Settings, THAWANI_SECRET_KEY and THAWANI_PUBLISHABLE_KEY in .env, and the currency OMR. See Payments.

A student paid but the course did not open

The course opens when Thawani confirms the payment on the return page. If the student closed the browser before coming back, the order stays "Pending". Check the session in the Thawani portal; if it is paid, the student can open /api/payments/thawani/return?order=CODE again, or refund it. Bank transfers open the course only when an admin marks the order paid.

"Not eligible" when issuing a certificate

The message says what is missing: lessons not marked complete, or required quizzes not passed. Adding a lesson to a course after a learner finished it makes their progress drop below 100% until they complete the new lesson; certificates already issued stay valid.

A quiz says "no attempts left"

The learner used every attempt allowed. Raise "Attempts allowed" on the quiz (0 = unlimited) in the quiz builder.

A video lesson shows no player

Only https links from YouTube, Vimeo, or direct .mp4, .webm or .m4v files are embedded. Other links are ignored for safety.

Pages show "namespace.key" instead of text

A translation is missing in messages/ar.json or messages/en.json. npm test lists every missing key.

The build stops with "JavaScript heap out of memory"

Give Node more memory: NODE_OPTIONS=--max-old-space-size=2048 npm run build.