RQ Dashboard

Common errors

• redis.exceptions.ConnectionError: Error 111 connecting to 127.0.0.1:6379. Connection refused.

  cause The Redis server is either not running, not accessible from the host where rq-dashboard is running, or is configured on a different host/port/database than specified.
  fix Start your Redis server. Verify your `REDIS_URL` environment variable is correctly set (e.g., `export REDIS_URL='redis://your_redis_host:6379/0'`) or that Redis is running on the default `localhost:6379/0`.

• ModuleNotFoundError: No module named 'rq_dashboard'

  cause The `rq-dashboard` library has not been installed, or the Python virtual environment where it was installed is not currently active.
  fix Install the library using `pip install rq-dashboard`. If using a virtual environment, activate it (`source .venv/bin/activate` or `conda activate your_env`).

• rq-dashboard: command not found

  cause The `rq-dashboard` executable script is not in your system's PATH. This typically happens when a virtual environment is not activated or pip's script directory is not in PATH.
  fix Activate your Python virtual environment (`source .venv/bin/activate`). If not using a virtual environment, ensure pip's script directory (e.g., `~/.local/bin`) is included in your system's PATH.

• werkzeug.exceptions.NotFound: 404 Not Found: The requested URL was not found on the server.

  cause When embedding `rq-dashboard` into a Flask application, the blueprint might not be registered correctly, or the `url_prefix` is wrong, leading to routes not being found.
  fix Ensure you have called `app.register_blueprint(blueprint, url_prefix="/rq")` (or your desired prefix) and are accessing the dashboard at the correct URL (e.g., `http://127.0.0.1:5000/rq`).

Warnings

• gotcha RQ Dashboard does not include built-in authentication or authorization. It's designed for use in a trusted environment or behind a proxy that handles security. Exposing it directly to the internet without protection is a significant security risk.
  Fix: Implement authentication/authorization using a reverse proxy (e.g., Nginx with Basic Auth), integrate with a Flask security extension (e.g., Flask-Login, Flask-Security-Too) if embedding, or restrict network access (e.g., firewall rules).
• gotcha The dashboard's connection to Redis must be explicitly configured, especially if your Redis server is not running on `localhost:6379` or uses a different database. Incorrect `REDIS_URL` settings are a common cause of startup failures.
  Fix: Set the `REDIS_URL` environment variable (e.g., `export REDIS_URL='redis://your_host:6379/1'`) before running `rq-dashboard` or configuring the Flask blueprint. Ensure Redis is running and accessible from the dashboard host.
• gotcha Compatibility issues can arise between `rq-dashboard` and significantly older or newer major versions of `RQ` (Redis Queue) itself. While `rq-dashboard` aims to be broadly compatible, certain API changes in `RQ` may lead to unexpected behavior.
  Fix: Ensure `rq-dashboard` is updated to a recent version that is compatible with your `RQ` version. Check the `rq-dashboard` release notes or `setup.py` for specific `RQ` version requirements.
• deprecated Support for Python 2.x has been officially dropped. `rq-dashboard` now requires Python 3 for all recent versions.
  Fix: Upgrade your Python environment to Python 3.6 or newer.

Install

• pip install rq-dashboard Install stable version

Imports

• blueprint
  wrong:

  import rq_dashboard

  correct:

  from rq_dashboard import blueprint

  For programmatic integration into a Flask application, you import the 'blueprint'. The main dashboard is typically run via the 'rq-dashboard' command line tool, which doesn't require a direct Python import.

Quickstart

This quickstart demonstrates how to integrate the RQ Dashboard into a minimal Flask application. This allows you to serve the dashboard alongside your existing Flask routes. Alternatively, you can run the dashboard as a standalone application using the `rq-dashboard` command-line tool after setting the `REDIS_URL` environment variable.

import os
from flask import Flask
from rq_dashboard import blueprint

# Configure Redis URL. rq-dashboard defaults to redis://localhost:6379/0
# Use an environment variable for production readiness.
os.environ['REDIS_URL'] = os.environ.get('REDIS_URL', 'redis://localhost:6379/0')

app = Flask(__name__)

# Set the RQ_DASHBOARD_REDIS_URL config for the blueprint
app.config["RQ_DASHBOARD_REDIS_URL"] = os.environ['REDIS_URL']

# Register the RQ Dashboard blueprint under a specific URL prefix
app.register_blueprint(blueprint, url_prefix="/rq")

@app.route("/")
def index():
    return "<p>Hello from Flask app. Go to <a href='/rq'>/rq</a> for RQ Dashboard.</p>"

if __name__ == "__main__":
    print(f"RQ Dashboard accessible at http://127.0.0.1:5000/rq")
    print(f"Connecting to Redis at: {app.config['RQ_DASHBOARD_REDIS_URL']}")
    # For local development, use debug=True. In production, use a WSGI server.
    app.run(debug=True)