Configure a custom error page Skip to main content
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Configure a custom error page
Published: May 15, 2018   -   Updated: Jun 22, 2018




This is an Early Access feature. To enable it, please contact Okta Support.

Configure a custom error page

Settings > Customization > Custom Error Pages

You can customize the text and the look and feel of error pages using an embedded HTML editor provided on the Custom Error Pages tab of the Customization page. When used together with custom URL domain (required) and custom Okta-hosted sign-in page, this feature offers a fully customized error page. Screenshot


Key benefits
  • Modify the current HTML/CSS and JavaScript as much as you like, or paste your own code in the embedded editor to create a completely transformed error page.
  • Easily preview your custom error page before publishing.


For this feature to work, Custom URL Domain must be configured.

  • Your custom error page can display only when end users access Okta through your custom URL domain. Otherwise, only the default Okta error page can display.
  • You can replace, but not edit, the provided macros when editing code in the embedded editor. For details, see the Important note below.
  • The custom error page feature is supported in mobile browsers but not supported for use with Okta Mobile.

  1. Go to Settings > Customization.
  2. Click the Custom Error Pages tab.
  3. Customize the error page using the embedded editor. Screenshot
  4. custErrorPage-numbered-88per

    If you are familiar with using HTML/CSS and JavaScript and want to change text, colors, line widths, page layout, button shapes, and other elements, use the embedded editor in the middle of the page to customize the code. The screenshot above shows the areas that you will most likely want to change, but feel free to change anything you like according to your needs.

    Important: You can replace, but not edit, the provided macros. To replace a macro, you must replace the text and the brackets that surround the text. Otherwise, your changes are not implemented and the original text or element is removed from the error page.

    For example, to replace the {{errorSummary}} macro with a custom description:


    <p class="o-form-explain">your custom description</p>


    <p class="o-form-explain">{{{your custom description}}}</p>

    For additional information about how to use and manipulate the provided code, see the articles listed in Related Topics

  5. (Highly recommended) Click Preview to preview your changes before you publish.
  6. (Optional) Click Reset to Default if you want to remove all of your customizations and restore the default HTML/CSS and JavaScript code.
  7. When you are finished, click Save and Publish.

Known Issue

The Early Access version of this feature does not identify specific errors in your custom code.