System Checks

Module Summary

next.dj contributes Django system checks for every subsystem. Run them through uv run python manage.py check and the framework reports configuration mistakes with a code and a hint.

Check Registration

next.checks.register_all runs during AppConfig.ready. It imports each subsystem checks module so the @register side effects take effect. The imported modules are next.conf.checks, next.pages.checks, next.urls.checks, next.components.checks, next.forms.checks, next.server.checks, and next.static.checks.

Most of these modules register checks. next.server.checks registers no Django system checks. The dependency injection layer contributes no Django system checks.

Shared Helpers

next.checks.common holds helpers reused across subsystem check modules. It is imported indirectly by those modules rather than by register_all.

Shared helpers used by per-subpackage system-check modules.

next.checks.common.errors_for_unknown_keys(config: dict[str, Any], *, allowed: frozenset[str], prefix: str) → list[CheckMessage]

Return an Error list when config contains keys outside allowed.

next.checks.common.get_first_app_pages_dir(file_router: FileRouterBackend) → Path | None

Return the first existing app pages directory, or None.

next.checks.common.get_first_root_pages_path(file_router: FileRouterBackend) → Path | None

Return the first entry from _get_root_pages_paths when defined.

next.checks.common.get_pages_directory(router: RouterBackend) → Path | None

Return one representative pages root directory for scanning checks.

next.checks.common.get_router_manager() → tuple[RouterManager | None, list[CheckMessage]]

Return a fresh RouterManager or initialisation errors.

next.checks.common.iter_scanned_page_pairs(router: RouterBackend) → Iterator[tuple[str, Path]]

Yield pairs from _scan_pages_directory when the router is scannable.

Subsystem Checks

Pages

System checks for the pages subsystem.

next.pages.checks.check_context_functions(*_args: object, **_kwargs: object) → list[CheckMessage]

Require keyless @context callables to return a dict when invoked.

next.pages.checks.check_context_processor_signature(*_args: object, **_kwargs: object) → list[CheckMessage]

Warn when a configured context processor has no request parameter.

next.pages.checks.check_layout_templates(*_args: object, **_kwargs: object) → list[CheckMessage]

Check layout.djx files for the {% block template %} structure.

next.pages.checks.check_page_functions(*_args: object, **_kwargs: object) → list[CheckMessage]

Validate each page module for render or template. Warn when empty.

next.pages.checks.check_pages_structure(*_args: object, **_kwargs: object) → list[CheckMessage]

Check each router’s pages tree for layouts, naming, and structure.

next.pages.checks.check_request_in_context(*_args: object, **_kwargs: object) → list[CheckMessage]

Ensure request is in the template context (required for {% form %}).

next.pages.checks.check_template_loaders(*_args: object, **_kwargs: object) → list[CheckMessage]

Validate every NEXT_FRAMEWORK[‘TEMPLATE_LOADERS’] entry.

URLs

System checks for the URL routing subsystem.

next.urls.checks.check_duplicate_url_parameters(*_args: object, **_kwargs: object) → list[CheckMessage]

Fail when the same bracket parameter name is repeated in one route.

next.urls.checks.check_next_pages_configuration(*_args: object, **_kwargs: object) → list[CheckMessage]

Validate DEFAULT_PAGE_BACKENDS inside merged NEXT_FRAMEWORK.

next.urls.checks.check_url_patterns(*_args: object, **_kwargs: object) → list[CheckMessage]

Collect patterns from routers and flag duplicate Django path strings.

Components

System checks for the components subsystem.

next.components.checks.check_component_py_no_pages_context(*_args: object, **_kwargs: object) → list[CheckMessage]

Check that component.py files do not use context from next.pages.

next.components.checks.check_cross_root_component_name_conflicts(*_args: object, **_kwargs: object) → list[CheckMessage]

Reject one component name in the root route scope on more than one page tree.

next.components.checks.check_duplicate_component_names(*_args: object, **_kwargs: object) → list[CheckMessage]

Check that no two components share the same name within the same scope.

next.components.checks.check_next_components_configuration(*_args: object, **_kwargs: object) → list[CheckMessage]

Validate DEFAULT_COMPONENT_BACKENDS shape in merged NEXT_FRAMEWORK.

Forms

System checks for the forms subsystem.

next.forms.checks.check_form_action_backends_configuration(*_args: object, **_kwargs: object) → list[CheckMessage]

Validate DEFAULT_FORM_ACTION_BACKENDS shape and import paths.

next.forms.checks.check_form_action_collisions(*_args: object, **_kwargs: object) → list[CheckMessage]

Flag two @action calls that share a name but come from different handlers.

Re-registration of the same handler (for example during autoreload) is safe and does not trigger the check because the fingerprint stays identical.

next.forms.checks.clear_action_collisions() → None

Drop the collision-check state. Intended for test isolation.

next.forms.checks.record_possible_collision(action_name: str, old_handler: Callable[..., Any], new_handler: Callable[..., Any]) → None

Record a collision when a name is re-registered with a distinct handler.

Called by RegistryFormActionBackend.register_action only on the overwrite path, so the common first-registration case pays nothing. Identity match (module reload of the exact same object) short-circuits before the fingerprint comparison.

Static

System checks for NEXT_FRAMEWORK[‘DEFAULT_STATIC_BACKENDS’].

The checks are hooked into manage.py check via the @register decorator. All identifiers live in the next.* namespace to avoid collisions with Django core checks.

Registered identifiers.

• next.W030. Warning raised when DEFAULT_STATIC_BACKENDS is empty. The framework falls back to the built-in staticfiles backend.

• next.E036. Error raised when a backend dotted path fails to import.

• next.E037. Error raised when the resolved class is not a StaticBackend subclass.

• next.E038. Error raised when the same BACKEND entry appears more than once in the configuration list.

• next.W031. Warning raised when OPTIONS[‘css_tag’] or OPTIONS[‘js_tag’] does not contain the {url} placeholder.

• next.W042. Warning raised when JS_CONTEXT_SERIALIZER is set but does not resolve to a class implementing the JsContextSerializer protocol.

next.static.checks.check_static_backends(app_configs: object, **_kwargs: object) → list[CheckMessage]

Validate the structure of NEXT_FRAMEWORK[‘DEFAULT_STATIC_BACKENDS’].

next.static.checks.check_js_context_serializer(*_args: object, **_kwargs: object) → list[CheckMessage]

Validate that JS_CONTEXT_SERIALIZER resolves to a protocol implementation.

Configuration

System checks for the configuration layer.

next.conf.checks.check_next_framework_unknown_top_level_keys(*_args: object, **_kwargs: object) → list[CheckMessage]

Reject keys under NEXT_FRAMEWORK that are not defined in defaults.

Server

next.server.checks registers no Django system checks, as noted under Check Registration.

Dependency Injection

The dependency injection layer does not contribute Django system checks. There is no next.ENNN code for a missing provider or a bad marker graph.

Note

Expect misconfiguration at runtime: unresolved parameters become None, and cycles raise DependencyCycleError. Troubleshooting lives in Dependency Injection and Troubleshooting.

Check Code Reference

The codes follow the Django convention next.X<NN> where X is E for errors and W for warnings.

Errors

Code	Condition	Emitted by
next.E001	NEXT_FRAMEWORK is not a dict, or DEFAULT_PAGE_BACKENDS is not a list.	next.urls.checks
next.E002	A DEFAULT_PAGE_BACKENDS or DEFAULT_COMPONENT_BACKENDS entry is not a dict.	next.urls.checks, next.components.checks
next.E003	A page backend entry does not specify BACKEND.	next.urls.checks
next.E004	A page backend entry names an unknown backend.	next.urls.checks
next.E005	The file router APP_DIRS value is not a boolean.	next.urls.checks
next.E006	The file router DIRS or OPTIONS has the wrong shape or an unknown key.	next.urls.checks
next.E007	The router manager fails to initialize.	next.checks.common
next.E008	A [param] directory uses invalid parameter syntax.	next.pages.checks
next.E009	A [[args]] directory uses invalid or incomplete args syntax.	next.pages.checks
next.E010	A parameter directory is missing its page.py file.	next.pages.checks
next.E011	An error was raised while checking page functions.	next.pages.checks
next.E012	A page.py has no body source: no render function, no template attribute, no loader match, and no sibling layout.djx.	next.pages.checks
next.E013	A page render attribute is not callable.	next.pages.checks
next.E014	An error was raised while checking URL conflicts.	next.urls.checks
next.E015	The same URL pattern is defined in more than one location.	next.urls.checks
next.E016	An error was raised while collecting patterns from a router.	next.urls.checks
next.E019	request is missing from the template context (required for {% form %} and CSRF).	next.pages.checks
next.E020	A component name is registered more than once within the same scope.	next.components.checks
next.E021	A component.py imports context from next.pages instead of next.components.	next.components.checks
next.E022	DEFAULT_PAGE_BACKENDS is empty.	next.urls.checks
next.E023	DEFAULT_COMPONENT_BACKENDS is not a list.	next.components.checks
next.E024	A file router entry is missing PAGES_DIR.	next.urls.checks
next.E025	A file router entry is missing APP_DIRS.	next.urls.checks
next.E026	A file router entry is missing OPTIONS.	next.urls.checks
next.E027	A COMPONENTS_DIR or PAGES_DIR value is not a string.	next.components.checks, next.urls.checks
next.E028	A route repeats the same bracket parameter name.	next.urls.checks
next.E029	A keyless @context callable is not annotated as returning a dict.	next.pages.checks
next.E030	An error was raised while checking router pages.	next.pages.checks
next.E031	A component backend entry is missing a required key.	next.components.checks
next.E032	A component backend BACKEND or DIRS value has the wrong type.	next.components.checks
next.E033	DEFAULT_COMPONENT_BACKENDS is empty.	next.components.checks
next.E034	A component name uses the shared root namespace on more than one page tree.	next.components.checks
next.E035	A configuration dict has unknown keys.	next.checks.common
next.E036	A static backend dotted path fails to import.	next.static.checks
next.E037	A static backend entry is not a dict, or the class is not a StaticBackend subclass.	next.static.checks
next.E038	DEFAULT_STATIC_BACKENDS contains a duplicate BACKEND entry.	next.static.checks
next.E040	A configured context processor does not accept a request parameter.	next.pages.checks
next.E041	A form action name is registered by more than one handler.	next.forms.checks
next.E042	A TEMPLATE_LOADERS entry is not a dotted-path string.	next.pages.checks
next.E043	A TEMPLATE_LOADERS entry cannot be imported or is not a TemplateLoader subclass.	next.pages.checks
next.E044	A form action backend entry has the wrong shape or cannot be imported.	next.forms.checks
next.E045	A form action backend class does not subclass FormActionBackend.	next.forms.checks

A code emitted by next.checks.common is produced by a shared helper that the listed subsystem check modules call.

Warnings

Code	Condition	Emitted by
next.W001	A layout.djx is missing the required {% block template %}.	next.pages.checks
next.W030	DEFAULT_STATIC_BACKENDS is empty, so the framework falls back to StaticFilesBackend.	next.static.checks
next.W031	An OPTIONS tag template is missing the {url} placeholder.	next.static.checks
next.W042	JS_CONTEXT_SERIALIZER is set but does not resolve to a usable serializer.	next.static.checks
next.W043	A page.py declares more than one body source and the lower-priority ones are ignored.	next.pages.checks

Note

Codes are assigned per check and are not contiguous. Inspect the source of each subsystem module above for the exact message text and trigger conditions.

See Also

See also

Installation for the first manage.py check run. Troubleshooting for symptoms that map to individual next.* codes.