1---
2title: Async Navigation Guards Require Proper Promise Handling
3impact: MEDIUM
4impactDescription: Unawaited promises in guards cause navigation to complete before async checks finish, allowing unauthorized access or missing data
5type: gotcha
6tags: [vue3, vue-router, navigation-guards, async, promises]
7---
8 
9# Async Navigation Guards Require Proper Promise Handling
10 
11**Impact: MEDIUM** - Navigation guards that perform async operations (API calls, auth checks) must properly handle promises. If you don't await async operations or return the promise, navigation completes before your check finishes, potentially allowing unauthorized access or navigating with incomplete data.
12 
13## Task Checklist
14 
15- [ ] Use async/await in navigation guards
16- [ ] Return the promise if not using async/await
17- [ ] Add loading states for long async operations
18- [ ] Implement timeouts for slow API calls
19- [ ] Handle errors to prevent navigation hanging
20 
21## The Problem
22 
23```javascript
24// WRONG: Not awaiting - navigation proceeds immediately
25router.beforeEach((to, from) => {
26  if (to.meta.requiresAuth) {
27    checkAuth()  // This returns a Promise but we're not waiting!
28    // Navigation continues before checkAuth completes
29  }
30})
31 
32// WRONG: Async function but forgot return
33router.beforeEach(async (to, from) => {
34  if (to.meta.requiresAuth) {
35    const isValid = await checkAuth()
36    if (!isValid) {
37      // This redirect might happen after navigation already completed!
38      return '/login'
39    }
40  }
41  // Missing return - implicitly returns undefined, allowing navigation
42})
43```
44 
45## Solution: Proper Async/Await Pattern
46 
47```javascript
48// CORRECT: Async function with proper returns
49router.beforeEach(async (to, from) => {
50  if (to.meta.requiresAuth) {
51    try {
52      const isAuthenticated = await checkAuth()
53 
54      if (!isAuthenticated) {
55        return { name: 'Login', query: { redirect: to.fullPath } }
56      }
57    } catch (error) {
58      console.error('Auth check failed:', error)
59      return { name: 'Error', params: { message: 'Authentication failed' } }
60    }
61  }
62  // Explicitly return nothing to proceed
63  return true
64})
65```
66 
67## Solution: Promise-Based Pattern (Alternative)
68 
69```javascript
70// CORRECT: Return promise explicitly
71router.beforeEach((to, from) => {
72  if (to.meta.requiresAuth) {
73    return checkAuth()
74      .then(isAuthenticated => {
75        if (!isAuthenticated) {
76          return { name: 'Login' }
77        }
78      })
79      .catch(error => {
80        console.error('Auth check failed:', error)
81        return { name: 'Error' }
82      })
83  }
84})
85```
86 
87## Loading State During Async Guards
88 
89```javascript
90// app/composables/useNavigationLoading.js
91import { ref } from 'vue'
92 
93const isNavigating = ref(false)
94 
95export function useNavigationLoading() {
96  return { isNavigating }
97}
98 
99export function setupNavigationLoading(router) {
100  router.beforeEach(() => {
101    isNavigating.value = true
102  })
103 
104  router.afterEach(() => {
105    isNavigating.value = false
106  })
107 
108  router.onError(() => {
109    isNavigating.value = false
110  })
111}
112```
113 
114```vue
115<!-- App.vue -->
116<script setup>
117import { useNavigationLoading } from '@/composables/useNavigationLoading'
118 
119const { isNavigating } = useNavigationLoading()
120</script>
121 
122<template>
123  <LoadingBar v-if="isNavigating" />
124  <router-view />
125</template>
126```
127 
128## Timeout Pattern for Slow APIs
129 
130```javascript
131// CORRECT: Add timeout to prevent indefinite waiting
132function withTimeout(promise, ms = 5000) {
133  return Promise.race([
134    promise,
135    new Promise((_, reject) =>
136      setTimeout(() => reject(new Error('Request timeout')), ms)
137    )
138  ])
139}
140 
141router.beforeEach(async (to, from) => {
142  if (to.meta.requiresAuth) {
143    try {
144      const isValid = await withTimeout(checkAuth(), 5000)
145      if (!isValid) {
146        return '/login'
147      }
148    } catch (error) {
149      if (error.message === 'Request timeout') {
150        // Let user through but show warning
151        console.warn('Auth check timed out')
152      } else {
153        return '/login'
154      }
155    }
156  }
157})
158```
159 
160## Multiple Async Checks
161 
162```javascript
163// CORRECT: Run independent checks in parallel
164router.beforeEach(async (to, from) => {
165  if (to.meta.requiresAuth && to.meta.requiresSubscription) {
166    try {
167      const [isAuthenticated, hasSubscription] = await Promise.all([
168        checkAuth(),
169        checkSubscription()
170      ])
171 
172      if (!isAuthenticated) {
173        return '/login'
174      }
175 
176      if (!hasSubscription) {
177        return '/subscribe'
178      }
179    } catch (error) {
180      return '/error'
181    }
182  }
183})
184```
185 
186## Error Handling Best Practices
187 
188```javascript
189router.beforeEach(async (to, from) => {
190  try {
191    // Your async logic here
192    await performChecks(to)
193  } catch (error) {
194    // Always handle errors to prevent navigation from hanging
195 
196    if (error.response?.status === 401) {
197      return '/login'
198    }
199 
200    if (error.response?.status === 403) {
201      return '/forbidden'
202    }
203 
204    if (error.code === 'NETWORK_ERROR') {
205      // Offline - maybe allow navigation but show warning
206      return true
207    }
208 
209    // Unknown error - redirect to error page
210    console.error('Navigation guard error:', error)
211    return { name: 'Error', state: { error: error.message } }
212  }
213})
214```
215 
216## Key Points
217 
2181. **Always await async operations** - Otherwise navigation proceeds immediately
2192. **Return values matter** - Return route to redirect, false to cancel, true/undefined to proceed
2203. **Handle all error cases** - Uncaught errors can hang navigation
2214. **Add timeouts** - Slow APIs shouldn't block navigation indefinitely
2225. **Show loading state** - Users need feedback during async checks
2236. **Parallelize independent checks** - Use Promise.all for better performance
224 
225## Reference
226- [Vue Router Navigation Guards](https://router.vuejs.org/guide/advanced/navigation-guards.html)
227- [Vue Router Navigation Failures](https://router.vuejs.org/guide/advanced/navigation-failures.html)
228