Troubleshooting

Last Updated: 2026-10-09 | Scope: Students, teachers, researchers, administrators, developers

Canonical triage page using: symptom -> likely cause -> fix.

Students and teachers

Students should contact their teacher or site support if these steps do not resolve the problem. Teachers and researchers can escalate deployment failures to the administrator. Include the time, lesson name, action, and error text; omit credentials and private learner records.

Administrator and developer diagnostics

Core libraries are served from the MoFaCTS site, including editor assets and the Anki importer's SQL WebAssembly file. If these fail to load, check the site's /vendor/ responses and the visible editor/import error. Serving these libraries locally does not make lessons, external media, AI, speech services, or sign-in available without a network connection.

The commands below are for operators with access to the deployment. Source development uses the managed watcher at http://localhost:3200; container deployment uses its configured URL and port. Begin from the repository's deploy/ directory and use the same private environment file as the running stack.

Step 0: Pick Your Deployment Branch

• Production (prebuilt image): you pull published image tags and run containers.
• Local dev: you run locally for development/debugging.
• Build from source: you build your own image artifacts.

If you are in production/prebuilt, do not start with source-build commands.

Step 1: Baseline Checks

docker compose --env-file .env.self-hosted -f docker-compose.yml ps
docker compose --env-file .env.self-hosted -f docker-compose.yml logs --tail 100 mofacts mongodb redis

Reachability:

• local source watcher: http://localhost:3200; use deploy/hotfix-local.ps1 -Action status and -Action logs
• self-hosted containers: configured ROOT_URL and MOFACTS_HTTP_BIND
• production: your HTTPS domain

Decision Tree

Symptom: Container will not start

• Likely cause: port conflict, invalid settings.json, low memory.
• Fix:
  • Check logs: docker logs mofacts --tail 200
  • Verify app port binding and host availability.
  • Validate settings.json JSON syntax and required keys.
  • Ensure minimum memory for your deployment size.

Branch-specific follow-up:

• Production (prebuilt): verify expected image tag, pull result, and mounted config paths.
• Build from source: verify Dockerfile/build context and dependency cache.

Symptom: 502 Bad Gateway in production

• Likely cause: app container down, reverse proxy down/misconfigured, wrong proxy target.
• Fix:
  • Confirm MoFaCTS container is healthy.
  • Confirm reverse proxy is healthy.
  • Verify upstream target points to app port (127.0.0.1:3000 or configured equivalent).
  • Verify firewall/security group rules.

Symptom: Cannot find module ...

• Likely cause: image/dependency mismatch.
• Fix:
  • Production (prebuilt): repull the expected tag and redeploy from runbook.
  • Build from source: rebuild using your documented build flow and verify lockfile/dependency integrity.
  • Recheck branch/tag/image alignment.

Symptom: Container keeps restarting

• Likely cause: bad runtime config, memory pressure, DB connectivity failure.
• Fix:
  • Inspect logs: docker logs mofacts --tail 200
  • Check container memory allocation.
  • Validate the private settings file named by METEOR_SETTINGS_HOST_PATH; Compose mounts it at /run/mofacts/settings.json.
  • Validate Mongo container health and credentials.

Symptom: Cannot connect to database

• Likely cause: Mongo not healthy, wrong credentials/connection string.
• Fix:
  • Inspect MongoDB readiness and the replica-set initializer before considering a restart:

    docker compose --env-file .env.self-hosted -f docker-compose.yml logs --tail 200 mongodb mongodb-replica-init
    

  • Verify Mongo URI and credentials in deployment config.

Symptom: TDF package upload fails

• Likely cause: bad package shape, invalid JSON, filename mismatches.
• Fix:
  • Ensure package contains required files.
  • Ensure stimulusfile in TDF matches actual uploaded stimulus filename exactly.
  • Validate JSON syntax and expected layout.

Symptom: Lesson does not appear for students

• Likely cause: assignment/config mismatch.
• Fix:
  • Confirm setspec.userselect is "true".
  • Confirm package upload succeeded.
  • Confirm class/section assignment context if the lesson is meant to be class-assigned.
  • Confirm the lesson is owned by, public to, or explicitly shared with the affected user.

Symptom: Questions render incorrectly

• Likely cause: malformed stimuli or missing media assets.
• Fix:
  • Validate stimulus JSON.
  • Verify required response fields and canonical names.
  • Verify media filenames match uploaded assets exactly.

Symptom: Speech recognition does not work

• Likely cause: keys/permissions/protocol/browser mismatch.
• Fix:
  • Verify speechAPIKey and audioInputEnabled.
  • Verify mic permission granted in browser.
  • Verify HTTPS in production.
  • Prefer Chrome/Edge.

Symptom: Text-to-speech does not work

• Likely cause: TTS config disabled or invalid key/voice.
• Fix:
  • Verify audioPromptMode is "question", "feedback", or "all" for the speech you expect.
  • Verify textToSpeechAPIKey and voice IDs.

Symptom: Students cannot log in

• Likely cause: account mismatch, bad URL, auth service issue.
• Fix:
  • Verify account exists.
  • Verify correct deployment URL.
  • Verify auth-related server logs.

Symptom: Progress not updating

• Likely cause: connectivity/session/write failure.
• Fix:
  • Verify network connectivity.
  • Refresh session and retry.
  • Check server logs for write errors.

Retired Mechanical Turk integration

Turk operations and scheduled reminders are no longer available. Old Turk unit fields and mturkSandbox settings are ignored; do not configure credentials or retry message delivery. Experiment login, lockout timing, and existing Prolific entry retain their ordinary behavior.

Environment-Specific Escalation

• Production (prebuilt): include deployed image tag, compose file version, and reverse proxy config snippet.
• Local dev: include local branch, startup command, and browser/runtime details.
• Build from source: include commit SHA, Dockerfile/build command, and build logs.

Related Guides

• Deployment Guide
• Remote Install
• Settings.json Reference
• Admin Reference
• Quick Start: Content Creation
• Audio and Speech Settings

When to Open an Issue

If unresolved, open a GitHub issue with:

1. exact error text
2. timestamp
3. environment branch (production/local/build-from-source)
4. relevant logs (mofacts, mongodb)
5. reproducible steps

• GitHub Issues