id="error-message-reporting">
   <title>Reporting Errors Within the Server</title>

   <indexterm>
    <primary>ereport</primary>
   </indexterm>
   <indexterm>
    <primary>elog</primary>
   </indexterm>

   <para>
    Error, warning, and log messages generated within the server code
    should be created using <function>ereport</function>, or its older cousin
    <function>elog</function>.  The use of this function is complex enough to
    require some explanation.
   </para>

   <para>
    There are two required elements for every message: a severity level
    (ranging from <literal>DEBUG</literal> to <literal>PANIC</literal>, defined
    in <filename>src/include/utils/elog.h</filename>) and a primary
    message text.  In addition there are optional elements, the most
    common of which is an error identifier code that follows the SQL spec's
    SQLSTATE conventions.
    <function>ereport</function> itself is just a shell macro that exists
    mainly for the syntactic convenience of making message generation
    look like a single function call in the C source code.  The only parameter
    accepted directly by <function>ereport</function> is the severity level.
    The primary message text and any optional message elements are
    generated by calling auxiliary functions, such as <function>errmsg</function>,
    within the <function>ereport</function> call.
   </para>

   <para>
    A typical call to <function>ereport</function> might look like this:
<programlisting>
ereport(ERROR,
        errcode(ERRCODE_DIVISION_BY_ZERO),
        errmsg("division by zero"));
</programlisting>
    This specifies error severity level <literal>ERROR</literal> (a run-of-the-mill
    error).  The <function>errcode</function> call specifies the SQLSTATE error code
    using a macro defined in <filename>src/include/utils/errcodes.h</filename>.  The
    <function>errmsg</function> call provides the primary message text.
   </para>

   <para>
    You will also frequently see this older style, with an extra set of
    parentheses surrounding the auxiliary function calls:
<programlisting>
ereport(ERROR,
        (errcode(ERRCODE_DIVISION_BY_ZERO),
         errmsg("division by zero")));
</programlisting>
    The extra parentheses were required
    before <productname>PostgreSQL</productname> version 12, but are now
    optional.
   </para>

   <para>
    Here is a more complex example:
<programlisting>
ereport(ERROR,
        errcode(ERRCODE_AMBIGUOUS_FUNCTION),
        errmsg("function %s is not unique",
               func_signature_string(funcname, nargs,
                                     NIL, actual_arg_types)),
        errhint("Unable to choose a best candidate function. "
                "You might need to add explicit typecasts."));
</programlisting>
    This illustrates the use of format codes to embed run-time values into
    a message text.  Also, an optional <quote>hint</quote> message is provided.
    The auxiliary function calls can be written in any order, but
    conventionally <function>errcode</function>
    and <function>errmsg</function> appear first.
   </para>

   <para>
    If the severity level is <literal>ERROR</literal> or higher,
    <function>ereport</function> aborts execution of the current query
    and does not return to the caller. If the severity level is
    lower than <literal>ERROR</literal>, <function>ereport</function> returns normally.
   </para>

   <para>
    The available auxiliary routines for <function>ereport</function> are:
  <itemizedlist>
   <listitem>
    <para>
     <function>errcode(sqlerrcode)</function> specifies the SQLSTATE error identifier
     code for the condition.  If this routine is not called, the error
     identifier defaults to
     <literal>ERRCODE_INTERNAL_ERROR</literal> when the error severity level is
     <literal>ERROR</literal> or higher, <literal>ERRCODE_WARNING</literal> when the
     error level is <literal>WARNING</literal>, otherwise (for <literal>NOTICE</literal>
     and