fix: surface observable errors via status instead of re-throwing

[tyler-reitz]

Problem

useObservable unconditionally re-throws errors from the underlying observable, making status: 'error' unreachable in practice. Users in non-suspense mode who want to handle errors locally have no way to do so:

const { status, error } = useStorageDownloadURL(ref);
if (status === 'error') return <NotFound />; // never reached -- error was already thrown

The original code included a TODO from the author questioning whether this behavior was correct.

Fix

Error handling now matches the mode the consumer opted into:

• Suspense mode (suspense: true): errors still throw, so React Error Boundaries catch them as expected. This preserves the idiomatic Suspense contract.
• Non-suspense mode (default or suspense: false): errors are returned via status: 'error' so consumers can handle them locally.

// non-suspense: handle locally
const { status, error } = useStorageDownloadURL(ref);
if (status === 'error') return <NotFound />;

// suspense: opt in to Error Boundary behavior
const { data } = useStorageDownloadURL(ref); // throws on error, caught by Error Boundary

Breaking change

This affects the default usage pattern. Non-suspense mode is the default — if you don't pass suspense: true or wrap your app in a SuspenseEnabledContext, you are in non-suspense mode.

Before 4.3.0, errors from any reactfire hook would throw unconditionally, regardless of mode. After 4.3.0:

• If you use non-suspense mode (the default) and rely on a React Error Boundary to catch Firebase errors, you must add an explicit check in your component:

  const { status, error } = useStorageDownloadURL(ref);
  if (status === 'error') throw error; // re-throw to reach Error Boundary

• If you use non-suspense mode and already check status, no change needed.
• Suspense mode behavior is unchanged.

Fixes #535, fixes #540

[gemini-code-assist]

Code Review

This pull request bumps the package version to 4.3.0 and modifies useObservable to surface errors via the status field instead of throwing them. Feedback highlights that completely removing the error throw breaks the React Suspense contract, where errors should be caught by an ErrorBoundary. It is recommended to conditionally throw errors when suspense is enabled and to update the tests accordingly.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.