error-states

Error handling patterns for Astro sites. 404/500 pages, form errors, offline states, loading failures. Use for graceful degradation and user experience.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for implementing robust error handling patterns in Astro applications. It focuses on maintaining user trust through graceful degradation, offering standardized solutions for custom error pages, accessible form validation, and offline resilience. By following these architectural best practices, developers can ensure their sites remain professional and helpful even during technical failures, significantly improving overall UX and site reliability.

Use Cases

  • Custom Error Pages: Designing branded 404 and 500 pages that provide helpful navigation and search options instead of generic browser messages.
  • Form Validation UX: Implementing accessible, non-blaming inline error messages and summaries to guide users through form completion.
  • Resilient Connectivity: Creating offline fallback pages and network-aware components to handle intermittent internet access gracefully.
  • Visual Feedback Systems: Integrating loading indicators and empty state components to keep users informed during asynchronous data fetching.
  • Production Monitoring: Establishing error logging patterns to track broken links and server-side exceptions for proactive maintenance.
nameerror-states
descriptionError handling patterns for Astro sites. 404/500 pages, form errors, offline states, loading failures. Use for graceful degradation and user experience.

Error States Skill

Purpose

Provides error handling patterns that maintain trust and guide users when things go wrong. Includes custom error pages, form validation states, loading indicators, offline fallbacks, and network error handling.

Core Rules

  1. Never blame the user — "We couldn't find that" not "Invalid request"
  2. Offer next steps — Always provide a way forward
  3. Keep branding — Error pages should match site design
  4. Be helpful — Search, popular links, contact info
  5. Log errors — Track 404s to fix broken links
  6. Accessible errors — Use ARIA labels and semantic HTML
  7. Loading feedback — Show spinners for async operations
  8. Network awareness — Handle offline states gracefully
  9. User-friendly messages — Translate HTTP codes to plain language
  10. Prevent error loops — Fail silently in error handlers

References

See the references/ directory for detailed implementations:

Forbidden

  • Technical jargon in error messages
  • Blaming users for errors
  • Generic "Something went wrong" with no next steps
  • Error pages without navigation
  • Silent failures (no feedback)
  • Ignoring 404 tracking

Definition of Done

  • Custom 404 page with search and links
  • Custom 500 page with recovery options
  • Form validation with inline errors
  • Loading states for async operations
  • Offline fallback page
  • Empty states for lists/search
  • Toast notifications for actions
  • Error logging in production
  • All error pages match site branding