Troubleshooting

Common issues and fixes

← Admin Panel

LRS returns HTTP 401 Unauthorized

Most common issue. Staging credentials expired or password copied incorrectly.

Login to integration.nelc.gov.sa via Nafath
Regenerate Staging keys and download JSON
Copy username and password exactly — no extra spaces
Update in LRS Endpoints → Edit staging or .env
Run Check health on staging

Health: Not configured

Endpoint missing URL, username, or password. Fill all three in the endpoint editor or .env, then re-check health.

Health: Unhealthy (timeout)

Verify server can reach lrs.nelc.gov.sa (firewall / proxy)
Check DNS and TLS interception on institutional network

Outbox stuck in RETRY

Usually transient LRS errors — dispatcher retries with exponential backoff
Check Logs category dispatcher
Fix credentials if 401 persists

Outbox DEAD status

HTTP 400 or 422 — invalid xAPI payload. Common causes:

Wrong context.platform (must be elearn.oc.edu.sa)
Invalid National ID format in actor.name
Missing required NELC extensions

Review error column in Outbox table and fix builder/config — dead rows are not auto-retried.

Quarantine learners

Blackboard user profile missing valid 10-digit National ID in the configured field (BB_NATIONAL_ID_FIELD, default studentId).

Populate National ID in Blackboard learner profiles
Re-run Poll Blackboard

Blackboard test fails

Verify BB_APP_KEY and BB_APP_SECRET in .env
REST integration must have scopes: course, user, enrollment, grade read
Integration must be Available: Yes in Blackboard admin

Unauthorized in admin UI

Enter correct ADMIN_TOKEN in top bar. If ADMIN_TOKEN=change-me-in-env, auth is disabled (development only).

Worker not running

Check WORKER_ENABLED=true in .env
Restart: python main.py serve or docker compose restart middleware
View Worker tab for last poll/dispatch times

Portal shows fewer than 30/30 approved

See NELC Portal Validation — all 7 verbs × correct learner/course combinations must reach staging LRS successfully.