1# Suspense Has No Built-in Error Handling
2 
3## Rule
4 
5`<Suspense>` does not provide error handling via the component itself. You must implement error handling using `errorCaptured` option or `onErrorCaptured()` hook in a parent component to catch async errors.
6 
7## Why This Matters
8 
9Without explicit error handling, async errors in suspended components will propagate uncaught, potentially crashing the application or leaving users stuck on loading states. Unlike React's Error Boundaries, Vue's Suspense requires manual error boundary implementation.
10 
11## Bad Code
12 
13```vue
14<script setup>
15// No error handling - async errors will propagate uncaught
16</script>
17 
18<template>
19  <Suspense>
20    <AsyncComponent />
21    <template #fallback>
22      Loading...
23    </template>
24  </Suspense>
25</template>
26```
27 
28## Good Code
29 
30```vue
31<script setup>
32import { ref, onErrorCaptured } from 'vue'
33import AsyncComponent from './AsyncComponent.vue'
34 
35const error = ref(null)
36 
37onErrorCaptured((err) => {
38  error.value = err
39  return false // Prevent error from propagating further
40})
41</script>
42 
43<template>
44  <div v-if="error" class="error-state">
45    <p>Something went wrong: {{ error.message }}</p>
46    <button @click="error = null">Retry</button>
47  </div>
48 
49  <Suspense v-else>
50    <AsyncComponent />
51    <template #fallback>
52      Loading...
53    </template>
54  </Suspense>
55</template>
56```
57 
58## Reusable Error Boundary Pattern
59 
60```vue
61<!-- ErrorBoundary.vue -->
62<script setup>
63import { ref, onErrorCaptured } from 'vue'
64 
65const props = defineProps({
66  fallback: {
67    type: String,
68    default: 'Something went wrong'
69  }
70})
71 
72const emit = defineEmits(['error'])
73 
74const error = ref(null)
75 
76onErrorCaptured((err, instance, info) => {
77  error.value = { err, instance, info }
78  emit('error', { err, instance, info })
79  return false
80})
81 
82const reset = () => {
83  error.value = null
84}
85 
86defineExpose({ reset })
87</script>
88 
89<template>
90  <slot v-if="!error" />
91  <slot v-else name="error" :error="error" :reset="reset">
92    <div class="error-boundary">
93      {{ fallback }}
94      <button @click="reset">Retry</button>
95    </div>
96  </slot>
97</template>
98```
99 
100```vue
101<!-- Usage -->
102<template>
103  <ErrorBoundary @error="logError">
104    <Suspense>
105      <AsyncDashboard />
106      <template #fallback>Loading dashboard...</template>
107    </Suspense>
108 
109    <template #error="{ error, reset }">
110      <DashboardError :error="error" @retry="reset" />
111    </template>
112  </ErrorBoundary>
113</template>
114```
115 
116## Key Points
117 
1181. Always wrap `<Suspense>` with error handling logic in production
1192. Use `onErrorCaptured` for Composition API or `errorCaptured` option for Options API
1203. Return `false` from the error handler to stop propagation
1214. Consider creating a reusable `ErrorBoundary` component to reduce boilerplate
1225. Provide a way for users to retry failed operations
123 
124## References
125 
126- [Vue.js Suspense Documentation](https://vuejs.org/guide/built-ins/suspense#error-handling)
127- [Vue.js onErrorCaptured](https://vuejs.org/api/composition-api-lifecycle#onerrorcaptured)
128