Skip to main content

Troubleshooting

Installation Issues​

Docker not found

Install Docker Desktop on Windows or macOS, or Docker Engine on Linux. After installation, ensure the Docker daemon is running before executing any dev.py commands.

Port already in use

If a required port is occupied by another process, identify it and either stop the conflicting process or change the port in compose.yaml.

On macOS/Linux:

lsof -i :8000

On Windows:

netstat -ano | findstr :8000

Common ports used by Orbit Classroom: 5173 (frontend), 8000 (API), 5432 (database), 6379 (Redis), 9999 (auth), 9000 (Inbucket).

Secrets not generated

If the .env file is missing or incomplete, delete it and re-run the secrets generator:

python scripts/dev.py secrets

Python not found (Windows)

Install Python 3.13 or later from python.org and ensure it is added to your system PATH during installation. Verify with python --version in a new terminal window.

Ollama Issues​

Ollama not detected

  1. Ensure Ollama is running. Start it with: 
    ollama serve
  2. Verify the endpoint is reachable at http://localhost:11434.
  3. Pull at least one model before configuring it in the Admin settings: 
    ollama pull smollm2

Model too slow or unresponsive

Large models require significant RAM and, ideally, a GPU. If responses are very slow or the system becomes unresponsive, switch to a smaller model. smollm2:1b is a lightweight option suitable for low-resource machines. Models like qwen3-coder require substantial hardware and are not recommended for development environments without dedicated GPU resources.

Application Issues​

Stuck on the waiting screen after sign-up

New accounts start with the UNASSIGNED role. An Admin must change your role before you can access the application. Contact your platform Admin and ask them to assign your account a role in Admin > Settings > Users.

Materials stuck in PROCESSING

  1. Verify the worker service is running: 
    python scripts/dev.py logs worker
  2. If you are using an external embedding model (OpenAI, etc.), verify that the correct API key is set in your .env file and that the key has not been revoked.
  3. Check the worker logs for specific error messages.

Chat not responding

  1. Go to Admin > Settings > Models and verify that an active model is configured.
  2. If using an external provider, check that the API key is valid and the provider's service is reachable.
  3. If using Ollama, verify that the Ollama service is running and the selected model has been pulled.

Cannot access a lesson

The lesson may be unpublished. Only published lessons are visible to students. Ask your Teacher to publish the lesson from the module editor.

Database Issues​

Migration errors on startup

If the database fails to initialize or migrations report errors, reset the local environment:

python scripts/dev.py clean
python scripts/dev.py up
warning

dev.py clean removes all Docker volumes. This deletes all local data including your database, uploaded files, and Redis state. Use it only in development.

Connection refused

If the API cannot connect to the database, check that the db service started successfully:

docker compose ps

The db service should show a healthy status. If it is in a restart loop, check its logs:

python scripts/dev.py logs db

Getting Help​

If the steps above do not resolve your issue:

  • Open an issue in the project repository with a description of the problem, the relevant service logs, and your environment details.
  • Contact: german.pinedo@mifral.com