django/django · error · NotImplementedError

subclasses may provide a check() method to verify the finder

Error message

subclasses may provide a check() method to verify the finder is configured correctly.

What it means

BaseFinder.check() raises NotImplementedError as a default. Django's system checks framework calls check() on each staticfiles finder to validate configuration; concrete finders (FileSystemFinder, AppDirectoriesFinder, DefaultStorageFinder) override it. A custom finder that subclasses BaseFinder without overriding check() triggers this only if something invokes the base check() — typically when running the system checks or collectstatic on a misbuilt custom finder.

Source

Thrown at django/contrib/staticfiles/finders.py:24

from django.contrib.staticfiles import utils
from django.core.checks import Error, Warning
from django.core.exceptions import ImproperlyConfigured
from django.core.files.storage import FileSystemStorage, Storage, default_storage
from django.utils._os import safe_join
from django.utils.functional import LazyObject, empty
from django.utils.module_loading import import_string

# To keep track on which directories the finder has searched the static files.
searched_locations = []


class BaseFinder:
    """
    A base file finder to be used for custom staticfiles finder classes.
    """

    def check(self, **kwargs):
        raise NotImplementedError(
            "subclasses may provide a check() method to verify the finder is "
            "configured correctly."
        )

    def find(self, path, find_all=False):
        """
        Given a relative file path, find an absolute file path.

        If the ``find_all`` parameter is False (default) return only the first
        found file path; if True, return a list of all found files paths.
        """
        raise NotImplementedError(
            "subclasses of BaseFinder must provide a find() method"
        )

    def list(self, ignore_patterns):
        """
        Given an optional list of paths to ignore, return a two item iterable

View on GitHub (pinned to b5388a3a80)

Solutions

Override check(self, **kwargs) in your custom finder; return a list of django.core.checks messages (often []).
Subclass a concrete finder (e.g., BaseStorageFinder) that already provides check().
If check is not applicable, define check(self, **kwargs): return [].

Example fix

// before
class MyFinder(BaseFinder):
    def find(self, path, find_all=False): ...
    def list(self, ignore_patterns): ...
    # check() missing -> NotImplementedError during `manage.py check`

// after
from django.core.checks import Error
class MyFinder(BaseFinder):
    def find(self, path, find_all=False): ...
    def list(self, ignore_patterns): ...
    def check(self, **kwargs):
        return []  # or return [Error(...)] for real checks

Defensive patterns

Strategy: type-guard

Validate before calling

from django.contrib.staticfiles.finders import BaseFinder

def finder_implements_check(finder_cls) -> bool:
    return getattr(finder_cls, 'check', None) is not getattr(BaseFinder, 'check', None)

# validate all configured finders before running checks:
from importlib import import_module
for path in settings.STATICFILES_FINDERS:
    mod, cls = path.rsplit('.', 1)
    assert finder_implements_check(getattr(import_module(mod), cls)), f'{path} missing check()'

Type guard

from django.contrib.staticfiles.finders import BaseFinder
def has_finder_check(finder_cls) -> bool:
    return 'check' in finder_cls.__dict__ or any('check' in vars(b) for b in finder_cls.__mro__[1:])

Prevention

Subclass a concrete finder (BaseStorageFinder) that already implements check().
Always define check(self, **kwargs): return [] on custom BaseFinder subclasses.
Add a unit test that runs `manage.py check` with your custom finder enabled.

When it happens

Trigger: A custom staticfiles finder (added to STATICFILES_FINDERS) subclasses BaseFinder directly and does not override check(); then `manage.py check`, collectstatic, or findstatic runs the finder's check() and hits the NotImplementedError.

Common situations: Writing a custom finder (e.g., for an S3/custom storage) and forgetting the check() method; using a third-party finder package that hasn't implemented check(); a check() invocation path that doesn't catch NotImplementedError.

Related errors

AI-assisted analysis of django/django@b5388a3a80 (2026-08-10). Data as JSON: /api/errors/8bb05fe95e228462. Report an issue: GitHub.