Skip to main content
Modulo

Troubleshooting

Getting started

Docker: port conflict on 5432

Modulo’s Docker Compose uses port 5434 for Postgres to avoid conflicts with local Postgres installations. If you see:

Error: starting container failed: port is already allocated

Check what’s running on port 5432 (your local Postgres) and 5434 (Docker). Either stop the conflicting service or change the port mapping in docker-compose.local.yml.

Alembic: migration fails with StringDataRightTruncationError

SQLAlchemyError: (psycopg2.errors.StringDataRightTruncationError) value too long for type character varying(32)

Branch-based Alembic migrations can produce revision IDs longer than 32 characters. Recreate the alembic_version table with a wider column:

docker compose exec db-local psql -U modulo -c "DROP TABLE IF EXISTS alembic_version; CREATE TABLE alembic_version (version_num VARCHAR(255) NOT NULL PRIMARY KEY);"
cd backend
uv run alembic upgrade heads

CORS: frontend can’t reach the API

Access to fetch at 'http://localhost:8000' from origin 'http://localhost:5173' has been blocked by CORS policy

Set CORS_ORIGINS=http://localhost:5173 in your backend/.env. Restart the backend. For production, include your domain: CORS_ORIGINS=https://modulo.run.

Redis: connection refused

Error connecting to Redis: connection refused

If you’re not using Redis features (WebSocket event broker), you can skip it. Redis is optional for basic pipeline execution. Comment out REDIS_URL in .env.

For full functionality, ensure Redis is running:

docker compose -f docker-compose.local.yml up -d

This starts both Postgres (port 5434) and Redis (port 6380).

Configuration

login: admin:admin doesn’t work

Check that:

  • MODULO_USERS=admin:admin is set in your backend/.env file
  • The backend started after the .env was created (restart if needed)
  • MODULO_DEMO_MODE=true will also seed a demo:demo user

Fernet key: malformed

ValueError: Fernet key must be 32 url-safe base64-encoded bytes

Generate a fresh key:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Set the output as FERNET_KEY in your .env. Do not use the example key from the docs.

GitHub connector: authentication fails

Verify:

  • The token has the correct scopes:
    • repo for private repos
    • contents: read for file access
    • pull_requests: write for PR comments
  • The token hasn’t expired
  • The connector config in the UI matches the token’s owner and repo

Running pipelines

Pipeline: stuck at HITL checkpoint

A human-in-the-loop (HITL) checkpoint pauses the pipeline until someone claims and approves it.

  1. Open the Pipeline Runs view
  2. Find the paused run (status: awaiting_human)
  3. Click Review to inspect the artifact
  4. Claim the review request (15-minute exclusive window)
  5. Approve to continue or Reject to stop

If no reviewers are configured, add a default reviewer in pipeline settings.

Next: Variant Execution (A/B Testing)