Django GraphiQL Debug Toolbar

Common errors

• The Debug Toolbar is not showing up in GraphiQL or any Django page.

  cause Common causes include `DEBUG` being `False`, `INTERNAL_IPS` not configured correctly, browser caching issues, or incorrect MIME type handling (especially on Windows).
  fix 1. Verify `DEBUG = True` and `INTERNAL_IPS` includes your request IP. 2. Clear your browser cache. 3. On Windows, ensure `.js` files are served with `Content-Type: text/javascript` by checking/modifying the registry `HKEY_CLASSES_ROOT\.js\Content Type`. 4. Ensure `graphiql_debug_toolbar.middleware.DebugToolbarMiddleware` is correctly placed in `MIDDLEWARE`.

• Server freezes or hangs at 'Performing system checks...' when `debug_toolbar` is enabled.

  cause This can happen if there's an incompatibility or a heavy check being performed by `django-debug-toolbar` or `django-graphiql-debug-toolbar` during startup, possibly related to specific Python, Django, or `django-debug-toolbar` versions.
  fix 1. Confirm Python, Django, and `django-debug-toolbar` versions are compatible. 2. Try isolating the issue by temporarily removing other `INSTALLED_APPS` or `MIDDLEWARE` entries. 3. In some cases, setting `PYTHONDEVMODE=1` before `runserver` might provide a stack trace on Ctrl-C.

• ModuleNotFoundError: No module named 'debug_toolbar'

  cause The `django-debug-toolbar` package, which is a core dependency, is not installed or not accessible in your Python environment.
  fix Ensure `django-debug-toolbar` is installed: `pip install django-debug-toolbar`. If using a virtual environment, ensure it's activated.

• AttributeError: 'NoneType' object has no attribute 'enabled_panels'

  cause This error usually indicates an issue within the interaction between `django-graphiql-debug-toolbar` and `django-debug-toolbar`, potentially due to version mismatches or an unusual configuration that leads to an uninitialized object.
  fix Check for known incompatibilities between `django-graphiql-debug-toolbar` and `django-debug-toolbar` versions on their respective GitHub issue trackers. Ensure all required `INSTALLED_APPS` and `MIDDLEWARE` entries for both libraries are present and correctly ordered.

Warnings

• breaking Version 0.2.0 removed support for Django versions older than 2.3. Ensure your Django project is on version 2.3 or higher before upgrading to 0.2.0.
  Fix: Upgrade Django to version 2.3 or higher, or pin `django-graphiql-debug-toolbar` to version <0.2.0.
• gotcha The toolbar requires `django-debug-toolbar` to be properly installed and configured first. Incompatibilities with `django-debug-toolbar` versions 4.4.6 or newer have been reported.
  Fix: Verify `django-debug-toolbar` is correctly installed and its basic functionality works. Check GitHub issues for known incompatibilities with specific `django-debug-toolbar` versions and consider pinning an older compatible version if issues arise.
• gotcha The `DebugToolbarMiddleware` must be placed correctly in your `MIDDLEWARE` list, ideally early but after any middleware that compresses content (like `GZipMiddleware`) and before any that might alter responses too heavily. Incorrect placement can prevent the toolbar from appearing or functioning.
  Fix: Ensure `graphiql_debug_toolbar.middleware.DebugToolbarMiddleware` is placed early in `MIDDLEWARE`, typically after Django's core middlewares but before any complex custom ones.
• gotcha The Debug Toolbar will only display if `settings.DEBUG` is set to `True` and the request's IP address is included in `settings.INTERNAL_IPS`.
  Fix: Set `DEBUG = True` in your `settings.py` for development. Add your local IP address (e.g., '127.0.0.1') to `INTERNAL_IPS`. If running in Docker or a VM, ensure `INTERNAL_IPS` includes the appropriate host IP.

Install

• pip install django-graphiql-debug-toolbar Install with pip

Imports

• DebugToolbarMiddleware
  wrong:

  from debug_toolbar.middleware import DebugToolbarMiddleware

  correct:

  from graphiql_debug_toolbar.middleware import DebugToolbarMiddleware

  This library replaces the standard Django Debug Toolbar middleware to integrate with GraphiQL.

Quickstart

To quickly set up `django-graphiql-debug-toolbar`, first install it and `django-debug-toolbar`. Then, modify your Django project's `settings.py` by adding `debug_toolbar` and `graphiql_debug_toolbar` to `INSTALLED_APPS`. Crucially, replace the default `DebugToolbarMiddleware` with `graphiql_debug_toolbar.middleware.DebugToolbarMiddleware` in your `MIDDLEWARE` list. Ensure `DEBUG` is `True` and `INTERNAL_IPS` is configured. Finally, include the `debug_toolbar.urls` in your project's `urls.py`, typically conditional on `settings.DEBUG`.

# settings.py

import os

DEBUG = True # Must be True for the toolbar to show

INSTALLED_APPS = [
    # ... other Django apps
    'django.contrib.staticfiles',
    'debug_toolbar',
    'graphiql_debug_toolbar',
    # 'graphene_django' if using Graphene,
    # ...
]

MIDDLEWARE = [
    # ... other middleware
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
    # Ensure this comes after other middleware that might encode content
    # and before any middleware that modifies the response too much.
    # Replace the standard DebugToolbarMiddleware with the GraphiQL version
    # 'debug_toolbar.middleware.DebugToolbarMiddleware',
    'graphiql_debug_toolbar.middleware.DebugToolbarMiddleware',
    # ...
]

INTERNAL_IPS = [
    '127.0.0.1',
    # Add other internal IPs if you're developing in a container/VM
    # '10.0.2.2', # For Android emulator if running Django in Docker
]

STATIC_URL = 'static/'

# urls.py (in your project's main urls.py)

from django.conf import settings
from django.urls import include, path

urlpatterns = [
    # ... your other url patterns
]

if settings.DEBUG:
    urlpatterns += [
        path('__debug__/', include('debug_toolbar.urls')),
    ]