exceptions.txt 7.93 KB
Newer Older
1 2 3 4
=================
Django Exceptions
=================

5
Django raises some of its own exceptions as well as standard Python exceptions.
6

7 8
Django Core Exceptions
======================
9 10

.. module:: django.core.exceptions
11 12
    :synopsis: Django core exceptions

13 14
Django core exception classes are defined in ``django.core.exceptions``.

15 16
``ObjectDoesNotExist``
----------------------
17 18

.. exception:: ObjectDoesNotExist
19

20 21 22
    The base class for :exc:`~django.db.models.Model.DoesNotExist` exceptions;
    a ``try/except`` for ``ObjectDoesNotExist`` will catch
    :exc:`~django.db.models.Model.DoesNotExist` exceptions for all models.
23

24
    See :meth:`~django.db.models.query.QuerySet.get()` for further information
25
    on :exc:`ObjectDoesNotExist` and :exc:`~django.db.models.Model.DoesNotExist`.
26

27 28 29
``FieldDoesNotExist``
---------------------

30 31 32 33 34 35
.. exception:: FieldDoesNotExist

    The ``FieldDoesNotExist`` exception is raised by a model's
    ``_meta.get_field()`` method when the requested field does not exist on the
    model or on the model's parents.

36 37 38
``MultipleObjectsReturned``
---------------------------

39
.. exception:: MultipleObjectsReturned
40

41 42 43 44 45
    The :exc:`MultipleObjectsReturned` exception is raised by a query if only
    one object is expected, but multiple objects are returned. A base version
    of this exception is provided in :mod:`django.core.exceptions`; each model
    class contains a subclassed version that can be used to identify the
    specific object type that has returned multiple objects.
46

47
    See :meth:`~django.db.models.query.QuerySet.get()` for further information.
48

49 50 51
``SuspiciousOperation``
-----------------------

52
.. exception:: SuspiciousOperation
53

54 55 56
    The :exc:`SuspiciousOperation` exception is raised when a user has
    performed an operation that should be considered suspicious from a security
    perspective, such as tampering with a session cookie. Subclasses of
57 58 59 60 61 62 63 64 65 66
    ``SuspiciousOperation`` include:

    * ``DisallowedHost``
    * ``DisallowedModelAdminLookup``
    * ``DisallowedModelAdminToField``
    * ``DisallowedRedirect``
    * ``InvalidSessionKey``
    * ``SuspiciousFileOperation``
    * ``SuspiciousMultipartForm``
    * ``SuspiciousSession``
67 68 69 70 71

    If a ``SuspiciousOperation`` exception reaches the WSGI handler level it is
    logged at the ``Error`` level and results in
    a :class:`~django.http.HttpResponseBadRequest`. See the :doc:`logging
    documentation </topics/logging/>` for more information.
72

73 74 75
``PermissionDenied``
--------------------

76
.. exception:: PermissionDenied
77

78 79
    The :exc:`PermissionDenied` exception is raised when a user does not have
    permission to perform the action requested.
80

81 82 83
``ViewDoesNotExist``
--------------------

84
.. exception:: ViewDoesNotExist
85

86
    The :exc:`ViewDoesNotExist` exception is raised by
87
    :mod:`django.urls` when a requested view does not exist.
88

89 90 91
``MiddlewareNotUsed``
---------------------

92
.. exception:: MiddlewareNotUsed
93

94 95
    The :exc:`MiddlewareNotUsed` exception is raised when a middleware is not
    used in the server configuration.
96

97 98 99
``ImproperlyConfigured``
------------------------

100
.. exception:: ImproperlyConfigured
101

102 103 104
    The :exc:`ImproperlyConfigured` exception is raised when Django is
    somehow improperly configured -- for example, if a value in ``settings.py``
    is incorrect or unparseable.
105

106 107 108
``FieldError``
--------------

109 110 111 112 113
.. exception:: FieldError

    The :exc:`FieldError` exception is raised when there is a problem with a
    model field. This can happen for several reasons:

114 115 116 117 118 119 120 121 122
    - A field in a model clashes with a field of the same name from an
      abstract base class
    - An infinite loop is caused by ordering
    - A keyword cannot be parsed from the filter parameters
    - A field cannot be determined from a keyword in the query
      parameters
    - A join is not permitted on the specified field
    - A field name is invalid
    - A query contains invalid order_by arguments
123

124 125 126
``ValidationError``
-------------------

127 128 129 130 131 132 133
.. exception:: ValidationError

    The :exc:`ValidationError` exception is raised when data fails form or
    model field validation. For more information about validation, see
    :doc:`Form and Field Validation </ref/forms/validation>`,
    :ref:`Model Field Validation <validating-objects>` and the
    :doc:`Validator Reference </ref/validators>`.
134

135 136 137
``NON_FIELD_ERRORS``
~~~~~~~~~~~~~~~~~~~~

138 139 140 141
.. data:: NON_FIELD_ERRORS

``ValidationError``\s that don't belong to a particular field in a form
or model are classified as ``NON_FIELD_ERRORS``. This constant is used
Szczepan Cieślik's avatar
Szczepan Cieślik committed
142
as a key in dictionaries that otherwise map fields to their respective
143 144
list of errors.

145
.. currentmodule:: django.urls
146

147 148 149
URL Resolver exceptions
=======================

150 151 152 153 154 155 156
URL Resolver exceptions are defined in ``django.urls``.

.. deprecated:: 1.10

    In older versions, these exceptions are located in
    ``django.core.urlresolvers``. Importing from the old location will continue
    to work until Django 2.0.
157 158 159

``Resolver404``
---------------
160

161 162 163
.. exception:: Resolver404

    The :exc:`Resolver404` exception is raised by
164 165
    :func:`~django.urls.resolve()` if the path passed to ``resolve()`` doesn't
    map to a view. It's a subclass of :class:`django.http.Http404`.
166 167 168

``NoReverseMatch``
------------------
169

170 171
.. exception:: NoReverseMatch

172 173 174
    The :exc:`NoReverseMatch` exception is raised by :mod:`django.urls` when a
    matching URL in your URLconf cannot be identified based on the parameters
    supplied.
175 176 177

.. currentmodule:: django.db

178 179 180
Database Exceptions
===================

181
Database exceptions may be imported from ``django.db``.
182

183
Django wraps the standard database exceptions so that your Django code has a
184
guaranteed common implementation of these classes.
185

186 187
.. exception:: Error
.. exception:: InterfaceError
188
.. exception:: DatabaseError
189 190
.. exception:: DataError
.. exception:: OperationalError
191
.. exception:: IntegrityError
192 193 194
.. exception:: InternalError
.. exception:: ProgrammingError
.. exception:: NotSupportedError
195

196
The Django wrappers for database exceptions behave exactly the same as
197 198
the underlying database exceptions. See :pep:`249`, the Python Database API
Specification v2.0, for further information.
199

200 201 202 203
As per :pep:`3134`, a ``__cause__`` attribute is set with the original
(underlying) database exception, allowing access to any additional
information provided. (Note that this attribute is available under
both Python 2 and Python 3, although :pep:`3134` normally only applies
204 205 206 207 208 209 210
to Python 3. To avoid unexpected differences with Python 3, Django will also
ensure that the exception made available via ``__cause__`` has a usable
``__traceback__`` attribute.)

.. versionchanged:: 1.10

    The ``__traceback__`` attribute described above was added.
211

212 213 214
.. exception:: models.ProtectedError

Raised to prevent deletion of referenced objects when using
215 216
:attr:`django.db.models.PROTECT`. :exc:`models.ProtectedError` is a subclass
of :exc:`IntegrityError`.
217 218 219 220 221 222

.. currentmodule:: django.http

Http Exceptions
===============

223
Http exceptions may be imported from ``django.http``.
224

225 226
``UnreadablePostError``
-----------------------
227

228
.. exception:: UnreadablePostError
229

230
    :exc:`UnreadablePostError` is raised when a user cancels an upload.
231 232 233 234

Transaction Exceptions
======================

235 236 237 238 239 240
.. currentmodule:: django.db.transaction

Transaction exceptions are defined in ``django.db.transaction``.

``TransactionManagementError``
------------------------------
241

242 243
.. exception:: TransactionManagementError

244
    :exc:`TransactionManagementError` is raised for any and all problems
245
    related to database transactions.
246

247 248 249 250 251
.. currentmodule:: django.test

Testing Framework Exceptions
============================

252 253 254 255
Exceptions provided by the ``django.test`` package.

``RedirectCycleError``
----------------------
256 257 258 259 260 261

.. exception:: client.RedirectCycleError

    :exc:`~client.RedirectCycleError` is raised when the test client detects a
    loop or an overly long chain of redirects.

262 263 264
Python Exceptions
=================

265
Django raises built-in Python exceptions when appropriate as well. See the
266
Python documentation for further information on the :ref:`bltin-exceptions`.