Skip to content
BlazorUI

AI

AiErrorView

Bit.BlazorUI.AI

BitAiErrorView shows an error the user can act on: what went wrong, a retry button when the error says retrying could help and a handler is there to do it, how long to wait before retrying when the provider says so, and the technical detail behind a disclosure rather than in the reader's face. It draws the error as an Error BitMessage, which is announced as an alert, and has a compact form for a failure shown inside another card.

Notes

To use this component, you need to install the Bit.BlazorUI.AI(opens in a new tab) nuget package, as described in the Optional steps of the Getting started page.

A chat message that failed, a failed tool call and a failed tool result show their BitAiError through this view by themselves. A transport reports a failure as a BitAiErrorEvent carrying one, so no component ever branches on an exception type of a provider's SDK; the session keeps the last one as LastError. The Message of an error is shown to the user and the Detail behind the disclosure, so keep secrets, keys and personal data out of both. See the Errors and Agent failure scenarios.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

Hand it the Error (a BitAiError). It is titled with a generic heading and shows the error's Message, written for the user. Nothing more is offered for an error that retrying would not fix.

Retry

The retry button is offered when the error says retrying could help (IsRetryable) and OnRetry is there to do it. RetryAfter says how long to wait first; the line saying it goes away once the wait is over. Here the scripted model is rate limited on the first try and answers on the second: the session reports the failure as its LastError, and RetryAsync runs the turn again. Start over brings back a model that fails once.


Detail

The Detail of an error - a status line, a response body - is kept behind the Show details disclosure, as it was written, and shown under it, next in the order the focus moves in. A long one scrolls past a few lines; it takes the focus itself, so it can be scrolled with a keyboard.


Retried 0 times.

Compact

Compact is for a failure inside another card that already says what failed - a tool call, a tool result: the view is titled by the error's own message rather than by the generic heading.

Monthly report

From an exception

BitAiError.FromException translates an exception for a transport or a tool of your own: a cancellation becomes a Cancelled error that retrying would not fix, a timeout a retryable Timeout, and anything else a retryable Unknown one carrying the exception's message. Never its stack trace, which would show the user the internals of the server: the exception stays on the error's Exception, for the app's logs, and is never shown.


Retried 0 times.

Disabled

Disabled turns the retry and the disclosure off, and drops the activation handlers the page put on the view.

Cascading parameters

BitParams with a BitAiErrorViewParams sets the defaults of every error view inside it - here the rounded retry buttons of a region. An error view keeps what it sets itself: the last one is disabled on its own.

Style & Class

Style and Class land on the root, Styles and Classes on the parts: the BitMessage the error is drawn with (restyled through its BitMessageClassStyles and --bit-Message-* variables), the text, the wait, the detail, the row of actions and the two buttons. The public --bit-AiErrorView-* variables restyle the detail.

RTL

In right-to-left text the error is laid out from the right. The heading, the buttons and the wait are the BitAiStrings of the options in force - here a subclass of them, cascaded by a BitAiOptionsProvider.


Retried 0 times.

CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle it - and any instance nested inside it, which inherits the value too; a parameter changes one alone, as does the real CSS property on the instance's Style / Styles when that property does not inherit (opacity: 1 keeps one disabled instance undimmed without undimming a disabled one inside it), while an inherited one such as color or font-family also reaches the nested instances that do not set it themselves. Leave a variable unset and the component falls back to the theme token beside it.

BitAiErrorView CSS variables

Name Default value Description
--bit-AiErrorView-detail-color var(--bit-clr-fg-sec) Color of the technical detail.
--bit-AiErrorView-detail-max-height spacing(24) Height past which the technical detail scrolls.

API

Every parameter, public member, sub-class and enum this component exposes.

BitAiErrorView parameters

Name Type Default value Description
Classes BitAiErrorViewClassStyles? null Custom CSS classes for different parts of the error view.
Compact bool false Renders the error for a place inside another card that already says what failed (a tool call, a tool result): it is titled by its own message instead of the generic heading, and the message is not repeated under it.
Error BitAiError The failure to show (required). Its Message is the text, IsRetryable decides whether the retry is offered, RetryAfter adds how long to wait, and Detail goes behind the disclosure.
OnRetry EventCallback Raised when the user asks to retry - typically BitAiChatSession.RetryAsync. The retry button is hidden while it is unset and while the error says retrying would not help (IsRetryable is false), and does nothing while the view is disabled.
Styles BitAiErrorViewClassStyles? null Custom CSS styles for different parts of the error view.

BitComponentBase parameters

Name Type Default value Description
AriaLabel string? null Gets or sets the accessible label for the component, used by assistive technologies.
Class string? null Gets or sets the CSS class name(s) to apply to the rendered element.
Dir BitDir? null Gets or sets the text directionality for the component's content.
Disabled bool false Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction.
ForceAnimation bool false Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested.
HtmlAttributes Dictionary<string, object> new Dictionary<string, object>() Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name.
Id string? null Gets or sets the unique identifier for the component's root element.
Style string? null Gets or sets the CSS style string to apply to the rendered element.
TabIndex string? null Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility BitVisibility BitVisibility.Visible Gets or sets the visibility state (visible, hidden, or collapsed) of the component.

BitComponentBase public members

Name Type Default value Description
UniqueId Guid Guid.NewGuid() Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement ElementReference Gets the reference to the root HTML element associated with this component.

BitAiErrorViewClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitAiErrorView.
Message BitMessageClassStyles? null Custom CSS classes/styles for the BitMessage the BitAiErrorView draws the error with: its surface, icon, title and content.
Text string? null Custom CSS classes/styles for the text of the error of the BitAiErrorView (not rendered when Compact, whose title is that text).
RetryAfter string? null Custom CSS classes/styles for the line saying how long to wait before retrying, of the BitAiErrorView.
Detail string? null Custom CSS classes/styles for the technical detail of the BitAiErrorView.
Actions string? null Custom CSS classes/styles for the row of the action buttons of the BitAiErrorView, rendered when there is a button to show.
RetryButton BitButtonClassStyles? null Custom CSS classes/styles for the retry button of the BitAiErrorView.
DetailButton BitButtonClassStyles? null Custom CSS classes/styles for the button disclosing the technical detail of the BitAiErrorView.

BitAiError properties

A transport- and provider-independent description of a failure, fit for display and for driving the retry (a sealed record). Transports translate their own exceptions into it, so no component branches on the exception type of a provider's SDK.

Name Type Default value Description
BitAiError(message) constructor Creates an error with the message to show to the user.
Message string A human-readable message, safe to show to the end user.
Code string? null A stable machine-readable code, for example rate_limit.
Kind BitAiErrorKind BitAiErrorKind.Unknown The kind of failure, which the app can drive its own recovery from. The view draws every kind the same way; an agent run ended with an error of the Cancelled kind (BitAiAgentRun.SetError) ends as cancelled rather than failed.
IsRetryable bool false Whether retrying the same request could plausibly succeed. The view offers the retry only when it is true.
RetryAfter TimeSpan? null How long to wait before retrying, when the provider says so. The view shows it under the message from when it is handed the error until the wait is over, then takes the line away (it is not counted down: the message is an alert, which would announce every second).
Detail string? null Additional technical detail, shown behind a disclosure rather than inline - to the user, so never a stack trace or anything else they must not read.
Exception Exception? null The originating exception, if any. Never serialized and never shown.
FromException(exception) BitAiError Translates an exception: an OperationCanceledException into a Cancelled error (code cancelled, not retryable), a TimeoutException into a retryable Timeout one (code timeout), anything else into a retryable Unknown one carrying the exception's message - which is shown, so a transport whose exceptions say what users must not read translates them itself. The stack trace is never put in the Detail, which is shown too; the exception stays on Exception, for the app's logs.

BitAiErrorKind enum

Name Value Description
Unknown 0 Unclassified failure.
Network 1 The network or the transport failed.
Authentication 2 Credentials are missing, invalid or expired.
Authorization 3 The caller is authenticated but not permitted.
RateLimit 4 The provider is rate limiting the caller.
ContextLength 5 The request exceeded the context window of the model.
ContentFilter 6 A safety system of the provider refused the request.
InvalidRequest 7 The provider rejected the request as malformed.
Provider 8 The provider failed internally.
Tool 9 A tool threw or returned a failure while running.
Timeout 10 The request timed out.
Cancelled 11 The caller cancelled the request.

BitVisibility enum

Name Value Description
Visible 0 The content of the component is visible.
Hidden 1 The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed 2 The component is hidden (display:none).

BitDir enum

Name Value Description
Ltr 0 Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl 1 Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto 2 Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.