Skip to content

Troubleshooting

Jump to bottom
Manu Murugesan edited this page Mar 13, 2026 · 3 revisions

Troubleshooting

Installation

ModuleNotFoundError: No module named 'urand'

The package isn't installed. Run:

pip install -e .

Or ensure requirements.txt is installed:

pip install -r requirements.txt

ImportError: cannot import name 'ColumnDT' from 'datatables'

There's a package name conflict. The system needs sqlalchemy-datatables, not datatables. Fix:

pip uninstall datatables
pip install sqlalchemy-datatables

confuse.NotFoundError or click.UsageError about missing factors

The config file doesn't match the expected study name. Check:

  1. URAND_CONFIG_FILE points to the right file
  2. URAND_STUDY_NAME matches a top-level key in that file
  3. The study section has treatments and factors defined

Database

sqlalchemy.exc.OperationalError: no such table

The database hasn't been initialized. Run:

flask createdb

sqlalchemy.exc.IntegrityError: UNIQUE constraint failed

You're trying to randomize a participant with an ID that already exists. Each participant ID must be unique within a study. Check existing participants:

urn -s "Study Name" export /tmp/check.csv && grep P001 /tmp/check.csv

The database file is locked

SQLite allows only one writer at a time. If a process crashed mid-write, the lock file (.db-wal, .db-shm) may persist. Wait a moment and retry — if the issue persists:

# Check for processes using the database
lsof urn-randomization.db

# If safe, remove the WAL files (ensure no other process is writing)
rm urn-randomization.db-wal urn-randomization.db-shm

Web Interface

Login redirects back to the login page

  • OAuth not configured: Check that GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET are set.
  • User not registered: The Google email must match a user created with flask add_user.
  • Session issues: Ensure FLASK_SECRET_KEY is set. Without it, sessions won't persist across requests.

Plots don't render / blank chart area

  • Bokeh version mismatch: The app requires Bokeh 3.x. Check: 
    python -c "import bokeh; print(bokeh.__version__)"
  • JavaScript blocked: Ensure your browser allows JavaScript from CDN sources. Bokeh loads its JS library from CDN.

DataTable shows "Processing..." forever

The server-side DataTable endpoint (/dtbl_participants) may be failing. Check the Flask console for errors. Common causes:

  • Database connection issues
  • Missing sqlalchemy-datatables package

Flash messages appear but no content loads

Check that the user is authenticated. Content is only rendered inside the {% if current_user.is_authenticated %} block.

REST API

{"message": "Please pass a value for factor ... with your request.", "status": 400}

A required parameter is missing. The API returns specific messages for each case:

  • Missing study: "Please pass a study name with your request."
  • Missing participant ID: "Please pass the participant id with your request."
  • Missing factor: "Please pass a value for factor {name} with your request."
  • Invalid factor value: "Invalid level supplied for factor {name}. Allowed levels are: [...]"

{"message": "Unauthorized request", "status": 401}

The API key is invalid. Verify it:

flask list_users

{"message": "Requested study does not exist.", "status": 404}

The study parameter doesn't match any study in the config. The name must match exactly (case-sensitive, including spaces).

Factor values rejected

Factor values must exactly match the levels defined in the config (case-sensitive). Check valid values:

curl "http://localhost:5000/study_config?api_key=KEY&study=Study+Name"

CLI

urn: command not found

The package isn't installed with the entry point. Install with:

pip install -e .

Or run directly:

python -m urand.cli -s "Study Name" randomize --id P001 --user admin

flask createdb does nothing

It may have run successfully but silently. Check the database file exists:

ls -la urn-randomization.db

Deployment

Render deploy fails with "No module named..."

Ensure requirements.txt includes all dependencies. The render.yaml build command should install them:

buildCommand: pip install -r requirements.txt && flask init-demo

Static files not loading in production

With Gunicorn, Flask serves static files. If behind a reverse proxy, ensure it's configured to pass through /static/ requests or serve them directly.

OAuth doesn't work after deployment

  • Add the production redirect URI to Google Cloud Console: https://your-domain.com/login/google/authorized
  • Ensure HTTPS is enabled (Google requires it for OAuth redirects in production)
  • Set OAUTHLIB_INSECURE_TRANSPORT=1 only for local HTTP development — never in production

Clone this wiki locally