Skip to content

feat: add static fallback error page for Kratos #2698

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jaygiang wants to merge 2 commits into
base: master
Choose a base branch
from
Open

feat: add static fallback error page for Kratos #2698

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
92d5a4f
feat: add static fallback error page for Kratos
jaygiang Jul 29, 2026
39c0519
fix: update color scheme to light only
jaygiang Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 0 additions & 17 deletions docs/kratos/fallback/error.mdx
View file
Open in desktop

This file was deleted.

290 changes: 290 additions & 0 deletions src/static/kratos/fallback/error.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,290 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="color-scheme" content="light" />
<title>This should be the Error UI | Ory</title>
<meta
name="description"
content="You ended up here because you didn't set the following configuration value: selfservice.flows.error.ui_url."
/>
<link
rel="canonical"
href="https://www.ory.com/docs/kratos/fallback/error"
/>
<link rel="icon" href="/docs/img/favico.png" />
<style>
/* Ory docs tokens — src/css/theme.css. Light only: with no JS there is no
way to read the docs theme preference, so the page renders the same for
everyone rather than following the OS setting. */
:root {
--bg: #fff;
--footer-bg: #f8fafc;
--text: #0f172a;
--text-muted: #64748b;
--heading: #0f172a;
--link: #6260ff;
--border: #cbd5e1;
--inline-bg: #f8fafc;
--code-bg: #f6f8fa;
--code-text: #393a34;
--code-key: #22863a;
--code-border: rgba(15, 23, 42, 0.08);
}

*,
*::before,
*::after {
box-sizing: border-box;
}

body {
display: flex;
flex-direction: column;
min-height: 100vh;
margin: 0;
background: var(--bg);
color: var(--text);
font-family: system-ui, sans-serif;
font-size: 16px;
line-height: 1.65;
-webkit-text-size-adjust: 100%;
font-feature-settings:
"liga" 1,
"calt" 1;
}

.masthead {
display: flex;
align-items: center;
height: 64px;
padding: 0 24px;
border-bottom: 1px solid var(--border);
}

.masthead a {
display: inline-flex;
color: var(--text);
border-radius: 4px;
}

.wrap {
flex: 1;
width: 100%;
max-width: 1032px;
margin: 0 auto;
padding: 40px 24px 64px;
}

h1 {
margin: 0 0 24px;
color: var(--heading);
font-size: 2.5rem;
font-weight: 400;
line-height: 1.25;
letter-spacing: -0.01em;
}

p {
margin: 0 0 20px;
}

a {
color: var(--link);
text-decoration: none;
}

a:hover {
text-decoration: underline;
}

a:focus-visible {
outline: 2px solid var(--link);
outline-offset: 2px;
}

code {
font-family: ui-monospace, monospace;
font-size: 0.9em;
}

p code {
padding: 0.1em 0.4em;
border: 1px solid var(--border);
border-radius: 4px;
background: var(--inline-bg);
overflow-wrap: anywhere;
-webkit-box-decoration-break: clone;
box-decoration-break: clone;
}

.snippet {
margin: 0 0 20px;
border-radius: 6px;
background: var(--code-bg);
overflow: hidden;
}

.snippet__title {
padding: 12px 16px;
border-bottom: 1px solid var(--code-border);
color: var(--code-text);
font-size: 0.875rem;
}

/* tabindex="0" in the markup keeps the clipped snippet scrollable by
keyboard on narrow viewports, matching Docusaurus' own CodeBlock. */
.snippet pre {
margin: 0;
padding: 16px;
overflow-x: auto;
color: var(--code-text);
line-height: 1.6;
}

.snippet pre:focus-visible {
outline: 2px solid var(--link);
outline-offset: -2px;
}

.snippet .key {
color: var(--code-key);
}

/* Mirrors src/components/welcomePage/WelcomeFooter.tsx */
footer {
padding: 24px 0;
border-top: 1px solid var(--border);
background: var(--footer-bg);
}

.footer__inner {
display: flex;
flex-wrap: wrap;
align-items: center;
justify-content: space-between;
gap: 16px;
max-width: 1024px;
margin: 0 auto;
padding: 0 24px;
}

.footer__legal {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 8px;
color: var(--text-muted);
font-size: 12px;
line-height: 1.5;
}

/* Underlined, unlike WelcomeFooter.tsx: the links share their color with
the adjacent text, so without one nothing marks them as clickable. */
.footer__legal a {
color: var(--text-muted);
text-decoration: underline;
}

.footer__sep {
color: var(--border);
}

@media (max-width: 640px) {
.masthead,
.footer__inner {
padding-left: 16px;
padding-right: 16px;
}

.wrap {
padding: 32px 16px 48px;
}

h1 {
font-size: 2rem;
}
}
</style>
</head>
<body>
<header class="masthead">
<a href="/docs/welcome" aria-label="Ory documentation">
<svg
width="41"
height="16"
viewBox="0 0 41 16"
fill="currentColor"
aria-hidden="true"
xmlns="http://www.w3.org/2000/svg"
>
<path
d="M32.8635 15.2992H29.7407L33.4048 8.00617L29.7407 0.699219H32.8635L34.9523 4.89846L37.0966 0.699219H40.15L32.8635 15.2992Z"
/>
<path
fill-rule="evenodd"
clip-rule="evenodd"
d="M23.5452 9.57046C25.4254 9.04903 26.8098 7.31093 26.8236 5.25303V5.21827V5.1835C26.8029 2.7015 24.8056 0.699219 22.3468 0.699219H16.4926V3.32722L18.6965 6.94941H16.4995V15.2992H19.2544V9.73036H20.4115L23.7979 15.2992H27.0371L23.5452 9.57046ZM21.9473 6.95636H22.3537C23.3041 6.95636 24.0755 6.17769 24.0755 5.21827C24.0755 4.25884 23.3041 3.48017 22.3537 3.48017H19.8192L21.9473 6.95636Z"
/>
<path
fill-rule="evenodd"
clip-rule="evenodd"
d="M7.3 0.699219C3.26762 0.699219 0 3.96684 0 7.99922C0 12.0316 3.26762 15.2992 7.3 15.2992C11.3324 15.2992 14.6 12.0316 14.6 7.99922C14.6 3.96684 11.3324 0.699219 7.3 0.699219ZM2.78095 7.99922C2.78095 10.4951 4.8041 12.5183 7.3 12.5183C9.79591 12.5183 11.8191 10.4951 11.8191 7.99922C11.8191 5.50331 9.79591 3.48017 7.3 3.48017C4.8041 3.48017 2.78095 5.50331 2.78095 7.99922Z"
/>
</svg>
</a>
</header>

<main class="wrap">
<h1>This should be the Error UI</h1>

<p>
You ended up here because you didn't set the following configuration
value:
</p>

<div class="snippet">
<div class="snippet__title">path/to/kratos/config.yml</div>
<pre tabindex="0"><code><span class="key">selfservice</span>:
<span class="key">flows</span>:
<span class="key">error</span>:
<span class="key">ui_url</span>: http://my-app.com/error</code></pre>
Comment on lines +247 to +252

@coderabbitai coderabbitai Bot Jul 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win

Use HTTPS in the copy-paste configuration example.

http://my-app.com/error looks like a production endpoint and encourages sending the error identifier over plaintext. Change it to https://my-app.com/error, or make the example explicitly local with an http://localhost/... URL.

Proposed fix 
-      <span class="key">ui_url</span>: http://my-app.com/error</code></pre>
+      <span class="key">ui_url</span>: https://my-app.com/error</code></pre>
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<div class="snippet">
<div class="snippet__title">path/to/kratos/config.yml</div>
<pre tabindex="0"><code><span class="key">selfservice</span>:
<span class="key">flows</span>:
<span class="key">error</span>:
<span class="key">ui_url</span>: http://my-app.com/error</code></pre>
<div class="snippet">
<div class="snippet__title">path/to/kratos/config.yml</div>
<pre tabindex="0"><code><span class="key">selfservice</span>:
<span class="key">flows</span>:
<span class="key">error</span>:
<span class="key">ui_url</span>: https://my-app.com/error</code></pre>
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/static/kratos/fallback/error.html` around lines 247 - 252, Update the
copy-paste configuration example in the error fallback snippet to use an HTTPS
URL for selfservice.flows.error.ui_url, changing the example endpoint from
http://my-app.com/error to https://my-app.com/error.

</div>

<p>
You can set this configuration value using environment variable
<code>SELFSERVICE_FLOWS_ERROR_UI_URL</code> as well!
</p>

<p>
If you don't know what that means, head over to
<a href="/docs/kratos/self-service/flows/user-facing-errors"
>User-Facing Error</a
>!
</p>
</main>

<footer>
<div class="footer__inner">
<div class="footer__legal">
<span>&copy; Ory Corp</span>
<span class="footer__sep" aria-hidden="true">&middot;</span>
<a
href="https://www.ory.com/privacy"
target="_blank"
rel="noopener noreferrer"
>Privacy</a
>
<span class="footer__sep" aria-hidden="true">&middot;</span>
<a
href="https://www.ory.com/tos"
target="_blank"
rel="noopener noreferrer"
>Terms of service</a
>
</div>
</div>
</footer>
</body>
</html>
Loading