<html>
<head>
<link href="mmres://user_interface_reference.css" rel="stylesheet" type="text/css">
<title>CFERROR</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
   <div id="Description">
   <table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
      <tr> 
         <td valign="top" class="name">CFERROR</td>
         <td valign="top" nowrap class="compatibility">&nbsp;</td>
      </tr>
      <tr>
         <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
      </tr>


    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Description</span>
<p>
Displays a custom HTML page when an error occurs. This lets you maintain a consistent look and feel among an application's functional and error pages.
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Category</span>
<p>
Exception handling tags, Extensibility tags, Application framework tags
</p>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="syntax"><span class="title">Syntax</span><pre>&lt;cferror 
   type = &quot;a type&quot;
   template = &quot;template_path&quot;
   mailTo = &quot;email_address&quot;
   exception = &quot;exception_type&quot;&gt;
</pre>    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">See also</span>
<p>
cfrethrow, cfthrow, cftry, Chapter&#160;14, "Handling Errors" in ColdFusion MX Developer's Guide.
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">History</span>
<p>
ColdFusion&#160;MX: Deprecated the monitor option of the exception attribute. It might not work, and might cause an error, in later releases.
</p>

<p>

</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Usage</span>
<p>
Use this tag to provide custom error messages for pages in an application. This lets you maintain a consistent look and feel within the application, even when errors occur. 
</p>

<p>
You generally embed this tag in your Application CFC or Application.cfm file to specify error-handling responsibilities for an entire application. You must put it in one of these files if you specify type=&quot;validation&quot;; ColdFusion ignores it on any other page. 
</p>

<p>
The cftry and cfcatch tags provide a more interactive way to handle ColdFusion errors within a ColdFusion page than the cferror tag, but the cferror tag is a good safeguard against general errors. 
</p>

<p>
To ensure that error pages display successfully, avoid using the cfencode utility to encode pages that include the cferror tag.
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Page types</span>
<p>
The following table describes the types of errors you can specify and code you can use on the pages that handle these error type: 
</p>

<p>
</p><div align="left">
<table border="1">
  <caption></caption>
  <tr align="center">    <th>&#160;</th>
    <th>&#160;</th>
    <th>&#160;</th>
</tr>
  <tr align="left">    <td>
<p>Exception</p></td>
    <td>
<p>Dynamically invoked by the CFML language processor when it detects an unhandled exception condition.</p>
<p>Uses the full range of CFML tags. Error variables must be in cfoutput tags.</p></td>
    <td>
<p>Can handle specific exception types or display general information for exceptions.</p></td>
</tr>
  <tr align="left">    <td>
<p>Request</p></td>
    <td>
<p>Includes the error variables described in the Error Variables section. </p>
<p>Cannot include CFML tags, but you can display values of the error variables by enclosing them in number signs (#), as in #error.MailTo#.</p></td>
    <td>
<p>Use as a backup error handler to other error handling methods, including exception type.</p></td>
</tr>
  <tr align="left">    <td>
<p>Validation</p></td>
    <td>
<p>Handles data input validation errors that occur when submitting a form that uses hidden form-field validation or onSubmit validation. </p>
<p>Cannot include CFML tags, but you can display values of the error variables by enclosing them in number signs (#), as in #Error.InvalidFields#.</p>
<p>You must specify the validation error handler in the Application.cfc or Application.cfm file. </p></td>
    <td>
<p>Handles hidden form-field or onSubmit format validation errors only.</p></td>
</tr>
</table>
</div>
<p>
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Error variables</span>
<p>
The exception-handling page specified in the cferror tag template attribute contains one or more error variables. ColdFusion substitutes the value of the error variable when an error displays.
</p>

<p>
The following table lists error variables:
</p>

<p>
</p><div align="left">
<table border="1">
  <caption></caption>
  <tr align="center">    <th>&#160;</th>
    <th>&#160;</th>
    <th>&#160;</th>
</tr>
  <tr align="left">    <td colspan="1" rowspan="3">
<p>Validation only</p></td>
    <td>
<p>error.validationHeader</p></td>
    <td>
<p>Validation message header text.</p></td>
</tr>
  <tr align="left">    <td>
<p>error.invalidFields</p></td>
    <td>
<p>Unordered list of validation errors.</p></td>
</tr>
  <tr align="left">    <td>
<p>error.validationFooter</p></td>
    <td>
<p>Validation message footer text.</p></td>
</tr>
  <tr align="left">    <td colspan="1" rowspan="9">
<p>Request and Exception</p></td>
    <td>
<p>error.diagnostics</p></td>
    <td>
<p>Detailed error diagnostics from ColdFusion&#160;MX.</p></td>
</tr>
  <tr align="left">    <td>
<p>error.mailTo</p></td>
    <td>
<p>E-mail address (same as value in cferror.MailTo).</p></td>
</tr>
  <tr align="left">    <td>
<p>error.dateTime</p></td>
    <td>
<p>Date and time when error occurred.</p></td>
</tr>
  <tr align="left">    <td>
<p>error.browser</p></td>
    <td>
<p>Browser that was running when error occurred.</p></td>
</tr>
  <tr align="left">    <td>
<p>error.remoteAddress</p></td>
    <td>
<p>IP address of remote client.</p></td>
</tr>
  <tr align="left">    <td>
<p>error.HTTPReferer</p></td>
    <td>
<p>Page from which client accessed link to page where error occurred.</p></td>
</tr>
  <tr align="left">    <td>
<p>error.template</p></td>
    <td>
<p>Page executing when error occurred.</p></td>
</tr>
  <tr align="left">    <td>
<p>error.generatedContent</p></td>
    <td>
<p>The content generated by the page up to the point where the error occurred.</p></td>
</tr>
  <tr align="left">    <td>
<p>error.queryString</p></td>
    <td>
<p>URL query string of client&#39;s request.</p></td>
</tr>
  <tr align="left">    <td colspan="1" rowspan="4">
<p>Exception only</p></td>
    <td>
<p>error.message</p></td>
    <td>
<p>Error message associated with the exception.</p></td>
</tr>
  <tr align="left">    <td>
<p>error.rootCause</p></td>
    <td>
<p>The root cause of the exception. This structure contains the information that is returned by a cfcatch tag. For example, for a database exception, the SQL statement that caused the error is in the error.RootCause.Sql variable. For Java exceptions, this variable contains the Java servlet exception reported by the JVM as the cause of the &quot;root cause&quot; of the exception.</p></td>
</tr>
  <tr align="left">    <td>
<p>error.tagContext</p></td>
    <td>
<p>Array of structures containing information for each tag in the tag stack. The tag stack consists of each tag that is currently open. </p></td>
</tr>
  <tr align="left">    <td>
<p>error.type</p></td>
    <td>
<p>Exception type. </p></td>
</tr>
</table>
</div>
<p>
</p>
<table>
  <tr valign="top">
    <td width="30"><strong>Note: </strong></td>
    <td>If type = &quot;exception&quot;, you can substitute the prefix cferror for Error; for example, cferror.diagnostics, cferror.mailTo, or cferror.dateTime. </td>
  </tr>
</table>    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Example</span><pre>&lt;h3&gt;cferror Example&lt;/h3&gt;

&lt;!--- Example of cferror call within a page.
       NOTE: If you use cferror type=&quot;VALIDATION&quot; you MUST put it in
       Application.cfc or Application.cfm ---&gt;
&lt;cferror type = &quot;REQUEST&quot;
template = &quot;request_err.cfm&quot;
mailTo = &quot;admin@mywebsite.com&quot;&gt;
&lt;!--- This query calls a non-existent datasource, triggering an error to be 
handled. ---&gt;
&lt;cfquery name=&quot;testQuery&quot; datasource=&quot;doesNotExist&quot;&gt;
select * from nothing
&lt;/cfquery&gt;

&lt;!--- Example of the page (request_err.cfm) to handle this error. ---&gt;
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;We&#39;re sorry -- An Error Occurred&lt;/title&gt;
&lt;/head&gt; 
&lt;body&gt;
&lt;h2&gt;We&#39;re sorry -- An Error Occurred&lt;/h2&gt;
&lt;p&gt;
If you continue to have this problem, please contact #error.mailTo#
with the following information:&lt;/p&gt;
&lt;p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;b&gt;Your Location:&lt;/b&gt; #error.remoteAddress#
&lt;li&gt;&lt;b&gt;Your Browser:&lt;/b&gt; #error.browser#
&lt;li&gt;&lt;b&gt;Date and Time the Error Occurred:&lt;/b&gt; #error.dateTime#
&lt;li&gt;&lt;b&gt;Page You Came From:&lt;/b&gt; #error.HTTPReferer#
&lt;li&gt;&lt;b&gt;Message Content&lt;/b&gt;:
&lt;p&gt;#error.diagnostics#&lt;/p&gt;
&lt;/ul&gt; 
</pre>
         </td>
      </tr>
   </table>
   </div>
<div id="TYPE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">TYPE</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Required</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Type of error that the custom error page handles. The type also determines how ColdFusion handles the error page. For more information, see "Specifying a custom error page" in Chapter&#160;14, "Specifying a custom error page," in ColdFusion MX Developer's Guide.</p><ul>

<li>exception: an exception of the type specified by the exception attribute.</li>

<li>validation: errors recognized by server-side type validation.</li>

<li>request: any encountered error.</li>
</ul>


  </td>
  </tr>
  </table>
</div>
<div id="TEMPLATE">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">TEMPLATE</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Required</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>Relative path to the custom error page. (A ColdFusion page was formerly called a template.)</p>

  </td>
  </tr>
  </table>
</div>
<div id="MAILTO">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">MAILTO</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">



<p>An e-mail address. This attribute is available on the error page as the variable error.mailto. ColdFusion does not automatically send anything to this address.</p>

  </td>
  </tr>
  </table>
</div>
<div id="EXCEPTION">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">EXCEPTION</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>

  <tr>
  <td valign="top" class="syntax">&nbsp;</td>
  <td valign="top" nowrap class="requirements">Optional</td>
  </tr>
  <tr>
  <td colspan="2" class="clearseparation">&nbsp;</td>
  </tr>
  <tr>
  <td valign="top" colspan="2" class="description">

<strong>Default value:</strong> "Any"


<p>Type of exception that the tag handles: </p><ul>

<li>application: application exceptions.</li>

<li>database: database exceptions.</li>

<li>template: ColdFusion page exceptions.</li>

<li>security: security exceptions.</li>

<li>object: object exceptions.</li>

<li>missingInclude: missing include file exceptions.</li>

<li>expression: expression exceptions.</li>

<li>lock: lock exceptions.</li>

<li>custom_type: developer-defined exceptions, defined in the cfthrow tag.</li>

<li>any: all exception types. </li>
</ul>

<p>For more information on exception types, see cftry.</p>

  </td>
  </tr>
  </table>
</div>

  </body>
</html>
