[[PageOutline(2-3,Contents)]] = Exceptions In programming '''exceptions''' are conditions of the program that require special processing. Handling exceptions is important, because to the user the program should function as if it were in a normal state whereby any exceptions that are encountered are handled in the background. See also [wikipedia:Exception_handling]. This page lists the most common exceptions in Trac core and database communication. == Custom Trac Exceptions Trac defines a set of custom exception types: * ''Exception'' * [=#TracBaseError `TracBaseError`] ([source:trunk/trac/core.py#/TracBaseError trac.core]): Exception base class for errors in Trac. //(since 1.1.2)// * [=#TracError `TracError`] ([source:trunk/trac/core.py#/TracError trac.core]): Standard Exception for errors in Trac. * [=#AdminCommandError `AdminCommandError`] ([source:trunk/trac/admin/api.py#/AdminCommandError trac.admin.api]): Exception raised when an admin command cannot be executed. * [=#ConfigurationError `ConfigurationError`] ([source:trunk/trac/config.py#/ConfigurationError trac.config]): Exception raised when a value in the configuration file is not valid. * [=#InvalidAttachment `InvalidAttachment`] ([source:trunk/trac/attachment.py#/InvalidAttachment trac.attachment]): Exception raised when attachment validation fails //(Deprecated since 1.3.2, removed in 1.5.1)//. * [=#InvalidRepository `InvalidRepository`] ([source:trunk/trac/versioncontrol/api.py#/InvalidRepository trac.versioncontrol.api]): Exception raised when initializing a repository fails. * [=#InvalidTicket `InvalidTicket`] ([source:trunk/trac/ticket/web_ui.py#/InvalidTicket trac.ticket.web_ui]): Exception raised when a ticket fails validation //(Deprecated since 1.3.2, removed in 1.5.1)//. * [=#InvalidWikiPage `InvalidWikiPage`] ([source:trunk/trac/wiki/web_ui.py#/InvalidWikiPage trac.wiki.web_ui]): Exception raised when a Wiki page fails validation //(Deprecated since Trac 0.11 and removed in Trac 1.1.2)//. * [=#Macro `MacroError`] ([source:trunk/trac/wiki/formatter.py#/MacroError trac.wiki.formatter]) Exception raised in macro when an argument is invalid //(Since Trac 1.0.11)//. * [=#ProcessorError `ProcessorError`] ([source:trunk/trac/wiki/formatter.py#/ProcessorError trac.wiki.formatter]) * [=#QuerySyntaxError `QuerySyntaxError`] ([source:trunk/trac/ticket/query.py#/QuerySyntaxError trac.ticket.query]): Exception raised when a ticket query cannot be parsed from a string. * [=#QueryValueError `QueryValueError`] ([source:trunk/trac/ticket/query.py#/QueryValueError trac.ticket.query]): Exception raised when a ticket query has bad constraint values. * [=#ResourceExistsError `ResourceExistsError`] ([source:trunk/trac/resource.py#/ResourceExistsError trac.resource]): Thrown when attempting to insert an existing resource * [=#ResourceNotFound `ResourceNotFound`] ([source:trunk/trac/resource.py#/ResourceNotFound trac.resource]): Thrown when a non-existent resource is requested * [=#TimeoutError `TimeoutError`] ([source:trunk/trac/db/pool.py#/TimeoutError trac.db.pool]): Exception raised by the connection pool when no connection has become available after a given timeout (Prior to 1.0.2dev-r12305, inherited directly from `Exception`). * [=#TracNotImplementedError `TracNotImplementedError`] ([source:trunk/trac/web/api.py#/TracNotImplementedError trac.web.api]) Exception raised when a `NotImplementedError` is trapped. This exception is for internal use only and should not be raised by plugins. Plugin should use `NotImplementedError`. //(Since 1.0.11)// * [=#TracValueError `TracValueError`] ([source:trunk/trac/core.py#/TracValueError trac.core]) Exception raised when a function or operator receives an argument that is the correct type, but inappropriate value. //(Since 1.2.1)// * [=#HTTPException `HTTPException`] ([source:trunk/trac/web/api.py#/HTTPException trac.web.api]): Representing a HTTP status code * [=#HTTPBadRequest `HTTPBadRequest`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 400 Bad Request * [=#HTTPUnauthorized `HTTPUnauthorized`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 401 Unauthorized * [=#HTTPPaymentRequired `HTTPPaymentRequired`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 402 Payment Required * [=#HTTPForbidden `HTTPForbidden`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 403 Forbidden * [=#HTTPNotFound `HTTPNotFound`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 404 Not Found * [=#HTTPMethodNotAllowed `HTTPMethodNotAllowed`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 405 Method Not Allowed * [=#HTTPNotAcceptable `HTTPNotAcceptable`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 406 Not Acceptable * [=#HTTPProxyAuthenticationRequired `HTTPProxyAuthenticationRequired`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 407 Proxy Authentication Required * [=#HTTPRequestTimeout `HTTPRequestTimeout`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 408 Request Timeout * [=#HTTPConflict `HTTPConflict`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 409 Conflict * [=#HTTPGone `HTTPGone`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 410 Gone * [=#HTTPLengthRequired `HTTPLengthRequired`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 411 Length Required * [=#HTTPPreconditionFailed `HTTPPreconditionFailed`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 412 Precondition Failed * [=#HTTPRequestEntityTooLarge `HTTPRequestEntityTooLarge`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 413 Request Entity Too Large * [=#HTTPRequestUriTooLong `HTTPRequestUriTooLong`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 414 Request-Uri Too Long * [=#HTTPUnsupportedMediaType `HTTPUnsupportedMediaType`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 415 Unsupported Media Type * [=#HTTPRequestedRangeNotSatisfiable `HTTPRequestedRangeNotSatisfiable`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 416 Requested Range Not Satisfiable * [=#HTTPExpectationFailed `HTTPExpectationFailed`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 417 Expectation Failed * [=#HTTPInternalError `HTTPInternalError`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 500 Internal Server Error //(removed in 1.3.1)// * [=#HTTPInternalServerError `HTTPServerInternalError`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 500 Internal Server Error //(since 1.3.1)// * [=#HTTPNotImplemented `HTTPNotImplemented`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 501 Not Implemented * [=#HTTPBadGateway `HTTPBadGateway`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 502 Bad Gateway * [=#HTTPServiceUnavailable `HTTPServiceUnavailable`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 503 Service Unavailable * [=#HTTPGatewayTimeout `HTTPGatewayTimeout`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 504 Gateway Timeout * [=#HTTPVersionNotSupported `HTTPVersionNotSupported`] ([source:trunk/trac/web/api.py#/_HTTPException_subclass_names trac.web.api]): 505 Http Version Not Supported * [=#RequestDone `RequestDone`] ([source:trunk/trac/web/api.py#/RequestDone trac.web.api]): Marker exception that indicates whether request processing has completed and a response was sent. * [=#ParseError `ParseError`] ([source:trunk/trac/versioncontrol/svn_authz.py#/ParseError trac.versioncontrol.svn_authz]): Exception thrown for parse errors in authz files * [=#GitError `GitError`] ([source:trunk/tracopt/versioncontrol/git/PyGIT.py#/GitError tracopt.versioncontrol.git.PyGIT]) * [=#GitErrorSha `GitErrorSha`] ([source:trunk/tracopt/versioncontrol/git/PyGIT.py#/GitErrorSha tracopt.versioncontrol.git.PyGIT]) * [=#Error `Error`] ([source:trunk/trac/db/tests/api.py#/Error trac.db.tests.api]) * ''!StandardError'', `TracBaseError` * [=#PermissionError `PermissionError`] ([source:trunk/trac/perm.py#/PermissionError trac.perm]): Insufficient permissions to complete the operation //(Removed in 1.3.3)// * ''!StandardError'' * ''!RuntimeError'', `TracBaseError` * [=#BackupError `BackupError`] ([source:trunk/trac/env.py#/BackupError trac.env]): Exception raised during an upgrade when the DB backup fails Hierarchy is inconsistent, even after addition of `TracBaseError` class (#11568). There doesn't seem to be any consistent pattern in inheriting from `TracError`. Some exceptions also inherit from built-in exception classes other than `Exception`. There also seem to be multiple naming conventions. Consider following PEP:0008#exception-names. But changing the existing hierarchy might be difficult without breaking backward compatibility. == Database Exceptions We can catch [pep:0249#exceptions Python DB API exceptions] in a database neutral way. (Since Trac 1.0, see #6348.) {{{#!python try: with env.db_transaction as db: ... except env.db_exc.IntegrityError, e: ... }}} The above example catches `sqlite.IntegrityError`, `MySQLdb.IntegrityError` or `psycopg.IntegrityError`, depending on the selected DatabaseBackend. ---- See [query:keywords~=exception tickets]