Debian Codegraph @

docs/ref/exceptions.txt

raw
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`.