Django Watchman

Common errors

• TypeError: 'str' object is not iterable

  cause The `WATCHMAN_CHECKS` setting in your Django `settings.py` is configured as a string instead of a sequence (list or tuple). This often happens when defining a single check without a trailing comma, e.g., `WATCHMAN_CHECKS = ('my.check')` instead of `WATCHMAN_CHECKS = ('my.check',)`.
  fix Change `WATCHMAN_CHECKS = 'my.check'` to `WATCHMAN_CHECKS = ('my.check',)` (for a tuple) or `WATCHMAN_CHECKS = ['my.check']` (for a list).

• Error connecting to Watchman: timed out waiting for response, while executing ('watch-project', 'my_app')

  cause This error typically occurs during Django development server startup when `pywatchman` (used by Django's `WatchmanReloader` for file watching) cannot connect to the Watchman daemon within the default timeout. This is not directly from `django-watchman` but is a common adjacent issue when using Watchman for auto-reloading.
  fix Ensure the Watchman daemon is installed and running (`brew install watchman` on macOS, or follow OS-specific instructions). If it still times out for large projects, you may need to increase the timeout for `pywatchman` or configure Watchman to ignore certain directories (e.g., `node_modules`).

• Watching for file changes with StatReloader

  cause You have `pywatchman` and `django-watchman` installed, but Django's development server is still using the default `StatReloader` instead of `WatchmanReloader` for file change detection. This means Watchman is not being utilized for faster reloads.
  fix Ensure `pywatchman` is correctly installed in your environment (`pip install pywatchman`) and that your Django project is properly set up to find and use it. In most cases, just having `pywatchman` installed is enough, but sometimes environment issues or conflicting settings can prevent its detection. Restarting your development server is often necessary.

• Database check failed: Access denied for user 'X'@'localhost' (using password: YES)

  cause The database check executed by `django-watchman` failed due to incorrect database credentials or permissions configured in your Django `DATABASES` settings.
  fix Verify that the database user, password, host, and port configured in your Django `settings.py` for the database connection are correct and have the necessary privileges to connect and perform a basic `SELECT` query.

Warnings

• breaking Version 1.0.0 dropped support for Python 2 and Django versions older than 2.0. Additionally, it removed the dependency on `django-jsonview` in favor of Django's built-in `JsonResponse`.
  Fix: Upgrade your Python environment to 3.10+ and Django to 2.0+ (preferably 4.2+), and remove `django-jsonview` from your dependencies if upgrading from pre-1.0.0 versions.
• deprecated Prior to version 1.3.0, `django-watchman` used `django.conf.urls.url()`. This function has been deprecated in modern Django versions (3.1+), which now primarily use `re_path()` or `path()`.
  Fix: Ensure your `urls.py` uses `re_path(r'^watchman/', include('watchman.urls'))` for compatibility with Django 3.1+.
• gotcha When configuring `WATCHMAN_CHECKS` in your settings, ensure it is a sequence (e.g., a list or a tuple), not a single string. For a tuple with one item, remember the trailing comma: `('my.custom.check',)`.
  Fix: If you encounter `TypeError: 'str' object is not iterable` or `ImportError` related to `WATCHMAN_CHECKS`, change your setting from `WATCHMAN_CHECKS = 'single.check'` to `WATCHMAN_CHECKS = ('single.check',)` or `WATCHMAN_CHECKS = ['single.check']`.
• gotcha The database health check in `django-watchman` might fail for Oracle databases when using `SELECT 1` without a `FROM` clause.
  Fix: Upgrade to `django-watchman` 1.5.0 or newer, which addresses this by using `SELECT 1 FROM DUAL` for Oracle.
• gotcha Version 1.4.0 included a security fix for a Regular Expression Denial of Service (ReDoS) vulnerability in the Authorization header parsing. Crafted input could lead to polynomial backtracking.
  Fix: Upgrade to `django-watchman` 1.4.0 or newer to mitigate the ReDoS vulnerability.

Install

• pip install django-watchman Install stable version

Imports

• watchman.urls
  wrong:

  from django.conf.urls import url, include # url() is deprecated in modern Django

  correct:

  from django.urls import re_path, include
  
  urlpatterns = [
      re_path(r'^watchman/', include('watchman.urls')),
  ]

  For modern Django versions, `re_path` should be used instead of `url`. The `include` function remains the standard way to incorporate URL configurations.
• watchman.views.bare_status

  from django.urls import path
  from watchman.views import bare_status
  
  urlpatterns = [
      path('watchman/bare/', bare_status),
  ]

  Used for a minimal HTTP 200/500 response, typically for load balancers. You must wire this up manually in your `urls.py`.

Quickstart

To quickly integrate `django-watchman`, add 'watchman' to your `INSTALLED_APPS` and include `watchman.urls` in your project's `urls.py`. This will provide a JSON status endpoint at `/watchman/` and an HTML dashboard at `/watchman/dashboard/`. For a simpler liveness probe, the `/watchman/ping/` endpoint is also available.

import os

# settings.py
INSTALLED_APPS = [
    # ... other apps
    'watchman',
]

# urls.py
from django.urls import re_path, include

urlpatterns = [
    # ... other url patterns
    re_path(r'^watchman/', include('watchman.urls')),
    # For a minimal status endpoint (optional)
    # from watchman.views import bare_status
    # re_path(r'^watchman/bare/$', bare_status),
]

# Optional: Protect with a token (add to settings.py)
# WATCHMAN_TOKEN = os.environ.get('WATCHMAN_TOKEN', 'your_secret_token')

# Run checks from command line (optional)
# python manage.py watchman -v 2