FAQ and troubleshooting

Questions about courses, learning paths, riders and reports.

• Is the course published? Draft and archived courses are hidden.
• Is it in a learning path assigned to the rider? Check Assigned training on the rider page.
• Is it locked? In a path with courses in order, the rider must pass the courses before it.
• Is the rider’s status inactive? Inactive riders can’t sign in.

• New paths start inactive. Tick Active and select Save path.
• “Manual / bulk assignment only” paths are only given with Assign now or the API.
• Flag paths are only given when a new flag is added. Earlier flags don’t count.
• Check the market, vehicle and nationality filters. Nationality must match exactly.
• Automatic rules skip suspended and inactive riders, and riders who had the path before.

The flag’s message says why: no active learning path is set up for that flag type, or a path exists but the rider doesn’t match its filters, is inactive, or already has that corrective training open. See Flag an issue.

Only for corrective training. For onboarding and auto-assigned paths, Assign now and the API, courses the rider already passed count: an assignment whose published courses were all passed before is completed straight away.

Corrective training (paths assigned by a flag) counts only passes after the flag, so the rider takes those courses again, also when they are flagged a second time. See How assignments are completed.

You’re signed in as a market manager. Those are shared by every market, so only full admins can change them. You can still manage the riders in your markets and assign learning paths to them with Assign now. See What market managers see and change.

Not in the admin panel yet. To stop a path, untick Active. Riders keep paths they already have. Ask IT if a record must be removed.

Open the rider, select Reset PIN in Details and give them the new PIN privately. Or send a one-tap link from Send course link. See Reset a rider’s PIN.

Translations don’t follow English changes. Select Re-translate for each language (this replaces manual edits), or make the same change in each language tab and save.

Publishing makes a course available; a learning path gives it to riders. Add it to a path with Learning pathsthenAdd course.

Normally it takes one to two minutes. If the server restarted while the AI was working, the job can’t finish: 15 minutes after it started it shows as failed, with “It stopped before finishing, most likely because the server restarted. Try again.”

• Failed course: use Try again with the file, or Delete the draft at the top of the page.
• Failed translation: open the language tab and select Retry translation, or Delete translation and confirm with Delete for good.

Yes. A finished course shows Review on the route, and the quiz can be taken again. A retake never lowers the recorded score or un-passes the course: the best score and the first completion date are kept on the proof, in reports and in the API.

No. It applies to the next quiz attempts only.

Yes. Export from RidersthenExport, edit the file, save it as CSV UTF-8 and import it. The export uses market codes, and imports accept codes or market names in the market column. See How imports update riders.

The file wasn’t saved as UTF-8. In Excel, save as “CSV UTF-8 (Comma delimited)” and import it again: riders are updated, not duplicated.

No. Without the WhatsApp Cloud API, reminders are only logged. Share links from rider pages, or ask IT to connect WhatsApp. See WhatsApp.

Many dashboard figures count all time, while reports filter on start or assignment dates. See Dashboard filters.

There is no preview. Add a test rider, assign the path to their rider ID with Assign now, and sign in to the rider app in a private browser window. Test riders count in figures.

IT adds admin accounts with SQL. See Admin accounts.

Questions riders ask. The rider guide (Arabic) answers most of them.

No. The rider app opens in the phone’s browser from a link or the sign-in page.

No. Riders need a connection. Progress is saved as they go, so they can continue later.

Courses can be in English, Arabic, Roman Urdu and Kurdish (Sorani). Buttons and menus are in English or Arabic; Roman Urdu and Kurdish riders see English buttons with courses in their language.

Links work for 14 days. The rider signs in with rider ID and PIN, or you send a new link.

After 5 attempts in 15 minutes, sign-in is blocked for that rider ID. Wait 15 minutes. Resetting the PIN doesn’t lift the block.

The AI key isn’t set on the server. Ask IT. Separately, a rider who asks more than 40 questions in an hour is asked to wait before asking more.

Server, configuration and integration problems.

• APP_URL must be the real address. If it starts with https://, the site must be opened over HTTPS, or the secure cookie isn’t kept.
• nginx must pass the Host and X-Forwarded headers (the provided config does).

The HTTPS certificate wasn’t renewed. The certificate for the server’s IP address lasts only about 6 days, so renewal must keep working.

• Check expiry dates with sudo certbot certificates and the timer with systemctl list-timers snap.certbot.renew.timer.
• Run sudo certbot renew --dry-run to see the error. Port 80 must be open and serve /.well-known/acme-challenge/ from /var/www/letsencrypt.
• Renew now with sudo certbot renew; the deploy hook reloads nginx.
• Opening the site by a different name or address than the certificate covers (for example the IP address when the certificate is for a domain) also shows this warning. See HTTPS.

SESSION_SECRET (or PIN_SECRET) changed. Put the old value back and restart, or give riders new PINs. See If SESSION_SECRET changes.

503: INTEGRATION_API_KEY isn’t set; set it and restart. 401: the x-api-key header is missing or the key is different.

Set a valid ANTHROPIC_API_KEY in .env and restart the app. Check the key is active in the Claude Console, and that the server can reach api.anthropic.com over HTTPS.

Check client_max_body_size 25m in the nginx site config. Course files are limited to 20 MB by the app, CSV imports to 25 MB.

Keep proxy_buffering off and proxy_read_timeout 300s in the nginx config, then sudo nginx -t && sudo systemctl reload nginx.

Nothing to do on the server. A course generation or translation still running 15 minutes after it started reads as failed, and the training team recovers it from the course page (see If a translation fails). A slow job that does finish after that still saves its result.

To avoid lost jobs, restart or update the app at a quiet time, when nobody is generating or translating a course.

Read the error text in the notifications table (query in Logs and monitoring). Common causes: the template isn’t approved, the template name or language doesn’t match, the token expired, or the phone number is wrong.

• Check sudo crontab -u lms -l for the job, and /var/log/rider-academy-reminders.log for errors.
• The job must cd into the app folder, use the full path of npm (which npm), and the log file must be owned by lms.
• Run it by hand to see the output: sudo -iu lms bash -c 'cd /var/www/boolanga-lms && npm run reminders'.

The app is using the embedded preview database, and it was damaged by a forced stop. On a server, set DATABASE_URL to PostgreSQL. On a laptop, stop the app, move the data/pglite folder aside and run npm run setup.

Another copy of the app is running. Check sudo -iu lms pm2 status and sudo ss -ltnp | grep 3000, and stop the extra process. Only the PM2 process of lms should run the app.