= Exceptions

== Custom Trac Exceptions
Trac defines a set of custom exception types:

* ''Exception''
  * [=#TracError `TracError`] ([source:trunk/trac/core.py#/TracError trac.core]): Exception base class 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.
    * [=#InvalidTicket `InvalidTicket`] ([source:trunk/trac/ticket/web_ui.py#/InvalidTicket trac.ticket.web_ui]): Exception raised when a ticket fails validation.
    * [=#InvalidWikiPage `InvalidWikiPage`] ([source:trunk/trac/wiki/web_ui.py#/InvalidWikiPage trac.wiki.web_ui]): Exception raised when a Wiki page fails validation. Not used anymore since 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.
    * [=#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`).
  * ''!StandardError''
    * [=#PermissionError `PermissionError`] ([source:trunk/trac/perm.py#/PermissionError trac.perm]): Insufficient permissions to complete the operation
    * ''!RuntimeError''
      * [=#BackupError `BackupError`] ([source:trunk/trac/env.py#/BackupError trac.env]): Exception raised during an upgrade when the DB backup fails.
  * [=#HTTPException `HTTPException`] ([source:trunk/trac/web/api.py#/HTTPException trac.web.api]): Representing a HTTP status code
  * [=#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])

This hierarchy seems fairly inconsistent. Consider using the `TracError` base class consistently.

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.

== DB Exceptions
We can catch [pep:0249#exceptions Python DB API exceptions] in a DB-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]