| 1 |
================= |
| 2 |
Django Exceptions |
| 3 |
================= |
| 4 |
|
| 5 |
Django raises some of its own exceptions as well as standard Python exceptions. |
| 6 |
|
| 7 |
Django Core Exceptions |
| 8 |
====================== |
| 9 |
|
| 10 |
.. module:: django.core.exceptions |
| 11 |
:synopsis: Django core exceptions |
| 12 |
|
| 13 |
Django core exception classes are defined in ``django.core.exceptions``. |
| 14 |
|
| 15 |
``AppRegistryNotReady`` |
| 16 |
----------------------- |
| 17 |
|
| 18 |
.. exception:: AppRegistryNotReady |
| 19 |
|
| 20 |
This exception is raised when attempting to use models before the :ref:`app |
| 21 |
loading process <app-loading-process>`, which initializes the ORM, is |
| 22 |
complete. |
| 23 |
|
| 24 |
``ObjectDoesNotExist`` |
| 25 |
---------------------- |
| 26 |
|
| 27 |
.. exception:: ObjectDoesNotExist |
| 28 |
|
| 29 |
The base class for :exc:`Model.DoesNotExist |
| 30 |
<django.db.models.Model.DoesNotExist>` exceptions. A ``try/except`` for |
| 31 |
``ObjectDoesNotExist`` will catch |
| 32 |
:exc:`~django.db.models.Model.DoesNotExist` exceptions for all models. |
| 33 |
|
| 34 |
See :meth:`~django.db.models.query.QuerySet.get()`. |
| 35 |
|
| 36 |
``EmptyResultSet`` |
| 37 |
------------------ |
| 38 |
|
| 39 |
.. exception:: EmptyResultSet |
| 40 |
|
| 41 |
``EmptyResultSet`` may be raised during query generation if a query won't |
| 42 |
return any results. Most Django projects won't encounter this exception, |
| 43 |
but it might be useful for implementing custom lookups and expressions. |
| 44 |
|
| 45 |
``FullResultSet`` |
| 46 |
----------------- |
| 47 |
|
| 48 |
.. exception:: FullResultSet |
| 49 |
|
| 50 |
``FullResultSet`` may be raised during query generation if a query will |
| 51 |
match everything. Most Django projects won't encounter this exception, but |
| 52 |
it might be useful for implementing custom lookups and expressions. |
| 53 |
|
| 54 |
``FieldDoesNotExist`` |
| 55 |
--------------------- |
| 56 |
|
| 57 |
.. exception:: FieldDoesNotExist |
| 58 |
|
| 59 |
The ``FieldDoesNotExist`` exception is raised by a model's |
| 60 |
``_meta.get_field()`` method when the requested field does not exist on the |
| 61 |
model or on the model's parents. |
| 62 |
|
| 63 |
``MultipleObjectsReturned`` |
| 64 |
--------------------------- |
| 65 |
|
| 66 |
.. exception:: MultipleObjectsReturned |
| 67 |
|
| 68 |
The base class for :exc:`Model.MultipleObjectsReturned |
| 69 |
<django.db.models.Model.MultipleObjectsReturned>` exceptions. A |
| 70 |
``try/except`` for ``MultipleObjectsReturned`` will catch |
| 71 |
:exc:`~django.db.models.Model.MultipleObjectsReturned` exceptions for all |
| 72 |
models. |
| 73 |
|
| 74 |
See :meth:`~django.db.models.query.QuerySet.get()`. |
| 75 |
|
| 76 |
``SuspiciousOperation`` |
| 77 |
----------------------- |
| 78 |
|
| 79 |
.. exception:: SuspiciousOperation |
| 80 |
|
| 81 |
The :exc:`SuspiciousOperation` exception is raised when a user has |
| 82 |
performed an operation that should be considered suspicious from a security |
| 83 |
perspective, such as tampering with a session cookie. Subclasses of |
| 84 |
``SuspiciousOperation`` include: |
| 85 |
|
| 86 |
* ``DisallowedHost`` |
| 87 |
* ``DisallowedModelAdminLookup`` |
| 88 |
* ``DisallowedModelAdminToField`` |
| 89 |
* ``DisallowedRedirect`` |
| 90 |
* ``InvalidSessionKey`` |
| 91 |
* ``RequestDataTooBig`` |
| 92 |
* ``SuspiciousFileOperation`` |
| 93 |
* ``SuspiciousMultipartForm`` |
| 94 |
* ``SuspiciousSession`` |
| 95 |
* ``TooManyFieldsSent`` |
| 96 |
* ``TooManyFilesSent`` |
| 97 |
|
| 98 |
If a ``SuspiciousOperation`` exception reaches the ASGI/WSGI handler level |
| 99 |
it is logged at the ``Error`` level and results in |
| 100 |
a :class:`~django.http.HttpResponseBadRequest`. See the :doc:`logging |
| 101 |
documentation </topics/logging/>` for more information. |
| 102 |
|
| 103 |
``PermissionDenied`` |
| 104 |
-------------------- |
| 105 |
|
| 106 |
.. exception:: PermissionDenied |
| 107 |
|
| 108 |
The :exc:`PermissionDenied` exception is raised when a user does not have |
| 109 |
permission to perform the action requested. |
| 110 |
|
| 111 |
``ViewDoesNotExist`` |
| 112 |
-------------------- |
| 113 |
|
| 114 |
.. exception:: ViewDoesNotExist |
| 115 |
|
| 116 |
The :exc:`ViewDoesNotExist` exception is raised by |
| 117 |
:mod:`django.urls` when a requested view does not exist. |
| 118 |
|
| 119 |
``MiddlewareNotUsed`` |
| 120 |
--------------------- |
| 121 |
|
| 122 |
.. exception:: MiddlewareNotUsed |
| 123 |
|
| 124 |
The :exc:`MiddlewareNotUsed` exception is raised when a middleware is not |
| 125 |
used in the server configuration. |
| 126 |
|
| 127 |
``ImproperlyConfigured`` |
| 128 |
------------------------ |
| 129 |
|
| 130 |
.. exception:: ImproperlyConfigured |
| 131 |
|
| 132 |
The :exc:`ImproperlyConfigured` exception is raised when Django is |
| 133 |
somehow improperly configured -- for example, if a value in ``settings.py`` |
| 134 |
is incorrect or unparseable. |
| 135 |
|
| 136 |
``FieldError`` |
| 137 |
-------------- |
| 138 |
|
| 139 |
.. exception:: FieldError |
| 140 |
|
| 141 |
The :exc:`FieldError` exception is raised when there is a problem with a |
| 142 |
model field. This can happen for several reasons: |
| 143 |
|
| 144 |
- A field in a model clashes with a field of the same name from an |
| 145 |
abstract base class |
| 146 |
- An infinite loop is caused by ordering |
| 147 |
- A keyword cannot be parsed from the filter parameters |
| 148 |
- A field cannot be determined from a keyword in the query |
| 149 |
parameters |
| 150 |
- A join is not permitted on the specified field |
| 151 |
- A field name is invalid |
| 152 |
- A query contains invalid order_by arguments |
| 153 |
|
| 154 |
``ValidationError`` |
| 155 |
------------------- |
| 156 |
|
| 157 |
.. exception:: ValidationError |
| 158 |
|
| 159 |
The :exc:`ValidationError` exception is raised when data fails form or |
| 160 |
model field validation. For more information about validation, see |
| 161 |
:doc:`Form and Field Validation </ref/forms/validation>`, |
| 162 |
:ref:`Model Field Validation <validating-objects>` and the |
| 163 |
:doc:`Validator Reference </ref/validators>`. |
| 164 |
|
| 165 |
``NON_FIELD_ERRORS`` |
| 166 |
~~~~~~~~~~~~~~~~~~~~ |
| 167 |
|
| 168 |
.. data:: NON_FIELD_ERRORS |
| 169 |
|
| 170 |
``ValidationError``\s that don't belong to a particular field in a form |
| 171 |
or model are classified as ``NON_FIELD_ERRORS``. This constant is used |
| 172 |
as a key in dictionaries that otherwise map fields to their respective |
| 173 |
list of errors. |
| 174 |
|
| 175 |
``BadRequest`` |
| 176 |
-------------- |
| 177 |
|
| 178 |
.. exception:: BadRequest |
| 179 |
|
| 180 |
The :exc:`BadRequest` exception is raised when the request cannot be |
| 181 |
processed due to a client error. If a ``BadRequest`` exception reaches the |
| 182 |
ASGI/WSGI handler level it results in a |
| 183 |
:class:`~django.http.HttpResponseBadRequest`. |
| 184 |
|
| 185 |
``RequestAborted`` |
| 186 |
------------------ |
| 187 |
|
| 188 |
.. exception:: RequestAborted |
| 189 |
|
| 190 |
The :exc:`RequestAborted` exception is raised when an HTTP body being read |
| 191 |
in by the handler is cut off midstream and the client connection closes, |
| 192 |
or when the client does not send data and hits a timeout where the server |
| 193 |
closes the connection. |
| 194 |
|
| 195 |
It is internal to the HTTP handler modules and you are unlikely to see |
| 196 |
it elsewhere. If you are modifying HTTP handling code, you should raise |
| 197 |
this when you encounter an aborted request to make sure the socket is |
| 198 |
closed cleanly. |
| 199 |
|
| 200 |
``SynchronousOnlyOperation`` |
| 201 |
---------------------------- |
| 202 |
|
| 203 |
.. exception:: SynchronousOnlyOperation |
| 204 |
|
| 205 |
The :exc:`SynchronousOnlyOperation` exception is raised when code that |
| 206 |
is only allowed in synchronous Python code is called from an asynchronous |
| 207 |
context (a thread with a running asynchronous event loop). These parts of |
| 208 |
Django are generally heavily reliant on thread-safety to function and don't |
| 209 |
work correctly under coroutines sharing the same thread. |
| 210 |
|
| 211 |
If you are trying to call code that is synchronous-only from an |
| 212 |
asynchronous thread, then create a synchronous thread and call it in that. |
| 213 |
You can accomplish this is with :func:`asgiref.sync.sync_to_async`. |
| 214 |
|
| 215 |
.. currentmodule:: django.urls |
| 216 |
|
| 217 |
URL Resolver exceptions |
| 218 |
======================= |
| 219 |
|
| 220 |
URL Resolver exceptions are defined in ``django.urls``. |
| 221 |
|
| 222 |
``Resolver404`` |
| 223 |
--------------- |
| 224 |
|
| 225 |
.. exception:: Resolver404 |
| 226 |
|
| 227 |
The :exc:`Resolver404` exception is raised by |
| 228 |
:func:`~django.urls.resolve()` if the path passed to ``resolve()`` doesn't |
| 229 |
map to a view. It's a subclass of :class:`django.http.Http404`. |
| 230 |
|
| 231 |
``NoReverseMatch`` |
| 232 |
------------------ |
| 233 |
|
| 234 |
.. exception:: NoReverseMatch |
| 235 |
|
| 236 |
The :exc:`NoReverseMatch` exception is raised by :mod:`django.urls` when a |
| 237 |
matching URL in your URLconf cannot be identified based on the parameters |
| 238 |
supplied. |
| 239 |
|
| 240 |
.. currentmodule:: django.db |
| 241 |
|
| 242 |
Database Exceptions |
| 243 |
=================== |
| 244 |
|
| 245 |
Database exceptions may be imported from ``django.db``. |
| 246 |
|
| 247 |
Django wraps the standard database exceptions so that your Django code has a |
| 248 |
guaranteed common implementation of these classes. |
| 249 |
|
| 250 |
.. exception:: Error |
| 251 |
.. exception:: InterfaceError |
| 252 |
.. exception:: DatabaseError |
| 253 |
.. exception:: DataError |
| 254 |
.. exception:: OperationalError |
| 255 |
.. exception:: IntegrityError |
| 256 |
.. exception:: InternalError |
| 257 |
.. exception:: ProgrammingError |
| 258 |
.. exception:: NotSupportedError |
| 259 |
|
| 260 |
The Django wrappers for database exceptions behave exactly the same as |
| 261 |
the underlying database exceptions. See :pep:`249`, the Python Database API |
| 262 |
Specification v2.0, for further information. |
| 263 |
|
| 264 |
As per :pep:`3134`, a ``__cause__`` attribute is set with the original |
| 265 |
(underlying) database exception, allowing access to any additional |
| 266 |
information provided. |
| 267 |
|
| 268 |
.. exception:: models.ProtectedError |
| 269 |
|
| 270 |
Raised to prevent deletion of referenced objects when using |
| 271 |
:attr:`django.db.models.PROTECT`. :exc:`models.ProtectedError` is a subclass |
| 272 |
of :exc:`IntegrityError`. |
| 273 |
|
| 274 |
.. exception:: models.RestrictedError |
| 275 |
|
| 276 |
Raised to prevent deletion of referenced objects when using |
| 277 |
:attr:`django.db.models.RESTRICT`. :exc:`models.RestrictedError` is a subclass |
| 278 |
of :exc:`IntegrityError`. |
| 279 |
|
| 280 |
.. currentmodule:: django.http |
| 281 |
|
| 282 |
HTTP Exceptions |
| 283 |
=============== |
| 284 |
|
| 285 |
HTTP exceptions may be imported from ``django.http``. |
| 286 |
|
| 287 |
``UnreadablePostError`` |
| 288 |
----------------------- |
| 289 |
|
| 290 |
.. exception:: UnreadablePostError |
| 291 |
|
| 292 |
:exc:`UnreadablePostError` is raised when a user cancels an upload. |
| 293 |
|
| 294 |
.. currentmodule:: django.contrib.sessions.exceptions |
| 295 |
|
| 296 |
Sessions Exceptions |
| 297 |
=================== |
| 298 |
|
| 299 |
Sessions exceptions are defined in ``django.contrib.sessions.exceptions``. |
| 300 |
|
| 301 |
``SessionInterrupted`` |
| 302 |
---------------------- |
| 303 |
|
| 304 |
.. exception:: SessionInterrupted |
| 305 |
|
| 306 |
:exc:`SessionInterrupted` is raised when a session is destroyed in a |
| 307 |
concurrent request. It's a subclass of |
| 308 |
:exc:`~django.core.exceptions.BadRequest`. |
| 309 |
|
| 310 |
Transaction Exceptions |
| 311 |
====================== |
| 312 |
|
| 313 |
.. currentmodule:: django.db.transaction |
| 314 |
|
| 315 |
Transaction exceptions are defined in ``django.db.transaction``. |
| 316 |
|
| 317 |
``TransactionManagementError`` |
| 318 |
------------------------------ |
| 319 |
|
| 320 |
.. exception:: TransactionManagementError |
| 321 |
|
| 322 |
:exc:`TransactionManagementError` is raised for any and all problems |
| 323 |
related to database transactions. |
| 324 |
|
| 325 |
.. currentmodule:: django.test |
| 326 |
|
| 327 |
Testing Framework Exceptions |
| 328 |
============================ |
| 329 |
|
| 330 |
Exceptions provided by the ``django.test`` package. |
| 331 |
|
| 332 |
``RedirectCycleError`` |
| 333 |
---------------------- |
| 334 |
|
| 335 |
.. exception:: client.RedirectCycleError |
| 336 |
|
| 337 |
:exc:`~client.RedirectCycleError` is raised when the test client detects a |
| 338 |
loop or an overly long chain of redirects. |
| 339 |
|
| 340 |
Python Exceptions |
| 341 |
================= |
| 342 |
|
| 343 |
Django raises built-in Python exceptions when appropriate as well. See the |
| 344 |
Python documentation for further information on the :ref:`bltin-exceptions`. |