How to customize root path and 404 pages to redirect to application login?

[FASupportBot]

We need to handle certain FusionAuth pages as redirects to our application's main login page:

• Accesses to the root path (e.g., https://login.example.com/)
• Invalid URLs (e.g., https://login.example.com/whatever)
• Other errors that are unactionable for the user

Why: Some of these pages are unbranded, and users save invalid links to login URLs, then contact support when they see unbranded error pages.

Is there a solution within FusionAuth for this use case?

[FASupportBot]

FusionAuth supports customization for some of these scenarios through themes, but not all:

1. Root Path Customization

This is possible. The Index page can be customized through your FusionAuth theme. You can add a redirect (for example, using JavaScript or a meta refresh tag) to send users to your application's login page.

Important: When FusionAuth can't identify the tenant (including when browsing to / without client_id or tenantId parameters), it uses the default tenant. To theme the root page:

1. Create a copy of the built-in theme — the default theme is immutable because it ships with FusionAuth
2. Edit the index template in your copy to include your redirect (using JavaScript like window.location.href = "https://yourapp.com/login" or HTML meta refresh)
3. Apply this theme to ALL tenants, including the default tenant
4. Test with tenant specified — try the root URL with tenantId or client_id to confirm your edited theme renders

See the Advanced Themes troubleshooting guide for more details on theme issues.

Related: GitHub Issue #378

2. OAuth Error Handling

This is also possible. The OAuth error page can be customized in your theme, so you can implement the same redirect approach for customers who saved stale or broken login links. The OAuth error template is available for customization and you can add JavaScript or meta refresh redirects to handle these scenarios.

Note that OAuth errors can also be returned as redirect parameters to your application's callback URL (depending on the OAuth flow), which allows your application to handle errors directly rather than showing the FusionAuth-hosted error page.

3. 404 Pages for Invalid URLs

This is NOT currently customizable. The 404 page cannot be customized, including on Cloud deployments. Requests to invalid paths (like /whatever) will show the default error page. This is a known limitation tracked in GitHub Issue #404, which requests additional themed error pages (including 404 and 500 pages).

Summary

You can handle root path and OAuth error redirects through theme customization by adding JavaScript redirects to the index and OAuth error templates. However, true 404 pages remain uncustomizable. CloudFront configuration is not exposed to customers on cloud deployments, so there's no workaround at that layer.

Related Documentation

• Advanced Themes Documentation - Complete guide to customizing FusionAuth themes
• Theme Templates - Full list of available templates including Index and OAuth error
• Theme Template Variables - Variables available in each template
• Index Template Variables - Specific to the root page
• OAuth Error Template Variables - Specific to OAuth error page
• OAuth Error API Documentation - How OAuth errors are returned
• Default Tenant Configuration - Understanding the default tenant