🚨 Error Handling

How Vue Router Citadel handles errors thrown by outpost handlers, timeouts, and afterEach failures.

📊 Error Flow

⚙️ Default Behavior

When no onError handler is provided:

1. Error is logged via logger.error (always — critical event)
2. Debug breakpoint error-catch triggers (if debug: true)
3. Navigation is blocked (BLOCK)

const citadel = createNavigationCitadel(router);

citadel.deployOutpost({
  name: 'broken',
  handler: () => {
    throw new Error('Something went wrong');
  },
});

// Navigation to any route → BLOCK
// Console: 🔴 [🏰 NavigationCitadel] Outpost "broken" threw error: Something went wrong

🔧 Custom Error Handler (onError)

Redirect users to an error page instead of blocking:

const citadel = createNavigationCitadel(router, {
  onError: (error, ctx) => {
    console.error('Navigation error:', error);
    return { name: 'error', query: { message: error.message } };
  },
});

The onError handler receives:

• error — the thrown Error instance
• ctx — the same handler context (verdicts, to, from, router, hook)

onError can return any verdict: ALLOW, BLOCK, or redirect.

WARNING

If onError itself throws an error, the citadel falls back to the default behavior — log and BLOCK.

⏱️ Timeout Errors

Timeouts follow a similar flow — if onTimeout is provided, it controls the outcome; otherwise navigation is blocked with a warning.

See Outpost Timeout for configuration, priority resolution, and examples.

🪝 afterEach Errors

Errors in afterEach outposts are handled differently:

• afterEach hooks cannot block navigation (Vue Router limitation)
• Errors are always logged via logger.error (critical event)
• Navigation proceeds regardless — the page is already rendered

citadel.deployOutpost({
  name: 'analytics',
  hooks: [NavigationHooks.AFTER_EACH],
  handler: () => {
    throw new Error('Analytics failed');
    // Error logged, but navigation is NOT affected
  },
});

Diagram Legend

Color	Meaning
🟢	Success, ALLOW, continue
🟡	Warning, redirect, deduplicate
🔴	Error, BLOCK, cancel
🔵	Logging (when logger is enabled)
🟣	Named debug breakpoint (debug: true)