features/errors

PlaybackErrorEvent

Emitted when a playback error occurs.

Properties

Property	Type
error?	PlaybackError

---

NavigationErrorEvent

Emitted when a navigation error occurs.

Properties

Property	Type
error?	NavigationError

---

useFormattedNavigationError()

function useFormattedNavigationError(): 
  | FormattedNavigationError
  | undefined;

Hook that returns the current navigation error formatted for display.

Native formats the error using the formatNavigationError callback configured in BrowserConfiguration, or falls back to default English messages.

The same formatted error is used by CarPlay and Android Auto error dialogs, ensuring consistent error presentation across your app and external controllers.

Returns

| FormattedNavigationError | undefined

Formatted error with title and message, or undefined if no error

Examples

// Basic usage
const error = useFormattedNavigationError()

if (error) {
  return <ErrorView title={error.title} message={error.message} />
}

// Configure custom formatting - override only specific errors or routes
configureBrowser({
  formatNavigationError: ({ error, defaultFormatted, path }) => {
    // Custom message for specific routes
    if (error.code === 'network-error' && path.startsWith('/json-api')) {
      return {
        title: 'API Server Not Running',
        message: 'Start the API server first'
      }
    }
    if (error.code === 'http-error') {
      return {
        title: t('error.serverError'),
        message: t('error.httpMessage', { status: error.statusCode })
      }
    }
    // Use default for other error types
    return defaultFormatted
  }
})

See

• BrowserConfiguration.formatNavigationError - Configure custom error formatting
• useNavigationError - Access the raw error with code and status details

---

getFormattedNavigationError()

function getFormattedNavigationError(): 
  | FormattedNavigationError
  | undefined;

Gets the current navigation error formatted for display. Native formats the error using the configured formatNavigationError callback, or falls back to default formatting.

Returns

| FormattedNavigationError | undefined

Formatted error with title and message, or undefined if no error

---

onFormattedNavigationError

const onFormattedNavigationError: NativeUpdatedValue<
  | FormattedNavigationError
| undefined>;

Subscribes to formatted navigation error changes.

Param

Called when the formatted navigation error changes

Returns

Cleanup function to unsubscribe

---

FormattedNavigationError

Re-exports FormattedNavigationError

---

useNavigationError()

function useNavigationError(): NavigationError | undefined;

Hook that returns the current navigation error and updates when it changes.

Returns

NavigationError | undefined

The current navigation error or undefined

---

getNavigationError()

function getNavigationError(): NavigationError | undefined;

Gets the current navigation error, if any.

Returns

NavigationError | undefined

The current navigation error or undefined if there is no error

---

onNavigationError

const onNavigationError: NativeUpdatedValue<NavigationErrorEvent>;

Subscribes to navigation error events.

Param

Called when a navigation error occurs

Returns

Cleanup function to unsubscribe

---

NavigationError

type NavigationError = object;

Properties

code

code: NavigationErrorType;

message

message: string;

statusCode?

optional statusCode: number;

HTTP status code when code is 'http-error'

statusCodeSuccess?

optional statusCodeSuccess: boolean;

True if HTTP status code was 2xx (success), useful when error is due to response parsing

---

NavigationErrorType

type NavigationErrorType = 
  | "content-not-found"
  | "network-error"
  | "http-error"
  | "callback-error"
  | "unknown-error";

Type of navigation error that occurred.

• 'content-not-found' - No route configured for the requested path, or route resolution returned no content. This is a configuration issue, not an HTTP 404 from the server.
• 'network-error' - Network request failed (connection error, timeout, no internet).
• 'http-error' - Server returned a non-2xx HTTP status code, or returned 2xx but response parsing failed. Check statusCode and statusCodeSuccess for details.
• 'callback-error' - The browse callback returned an error (e.g., { error: 'message' }). Use this for business logic errors like authentication failures or subscription requirements.
• 'unknown-error' - An unexpected error occurred (e.g., invalid configuration).

---

usePlaybackError()

function usePlaybackError(): PlaybackError | undefined;

Hook that returns the current playback error and updates when it changes.

Returns

PlaybackError | undefined

The current playback error or undefined

---

getPlaybackError()

function getPlaybackError(): PlaybackError | undefined;

Gets the current playback error, if any.

Returns

PlaybackError | undefined

The current error or undefined if there is no error

---

onPlaybackError

const onPlaybackError: NativeUpdatedValue<PlaybackErrorEvent>;

Subscribes to playback error events.

Param

Called when a playback error occurs

Returns

Cleanup function to unsubscribe

---

PlaybackError

type PlaybackError = object;

Properties

code

code: string;

message

message: string;