Enhanced error messages with troubleshooting hints and documentation links

Open Copilot opened this issue 2 months ago • 0 comments

Description

Implements developer-friendly error messages that automatically detect common failure scenarios and provide actionable troubleshooting guidance. Transforms generic exceptions into contextual messages with hints, documentation links, and actor context.

Changes Made

Error Framework Components (1,983 lines across 13 files)

ErrorType enum: 15 error categories (bean not found, timeouts, cluster issues, serialization, etc.)
ErrorContext builder: Captures actor path, message type, state, and custom metadata
TroubleshootingHints singleton: YAML-based hint database (130+ lines) with variable substitution
ErrorMessageBuilder: Dual formatting modes (compact for prod, verbose boxed format for dev)
ActorErrorMessage API: Static methods for error detection and formatting

Error Detection

Automatic categorization via exception type and message analysis
Context-aware hint generation with variable substitution ({actorPath}, {messageType}, etc.)
Documentation link generation for all error types

Hint Database (error-hints.yml)

Configuration errors: missing annotations, invalid YAML, port conflicts
Messaging errors: ask timeouts, dead letters, unhandled messages
Lifecycle errors: spawn failures, restart loops, supervision issues
Cluster errors: formation failures, split brain, unreachable nodes
Serialization errors: Jackson configuration, non-serializable fields

Usage Example

// Basic
String msg = ActorErrorMessage.formatCompact(exception);

// With context
ErrorContext ctx = ErrorContext.builder()
    .actorPath("/user/order-actor")
    .messageType("CreateOrder")
    .additionalInfo("timeout", "3s")
    .build();
String msg = ActorErrorMessage.formatVerbose(exception, ctx);

Output Formats

Compact (production):

BeanCreationException: orderRepository not found
💡 Hint: Ensure OrderActor is annotated with @Component, @Repository, or @Service
📖 Docs: https://docs.spring-actor.io/troubleshooting#bean-not-found
🎯 Actor: /user/order-actor

Verbose (development):

╭─ BeanCreationException ──────────────────────────────────────────╮
│ orderRepository not found                                         │
│                                                                   │
│ 💡 Troubleshooting hints:                                         │
│   1. Ensure OrderActor is annotated with @Component, @Repository│
│   2. Check if component scanning includes the package            │
│   3. Verify that the Spring context is properly configured      │
│   4. Check if required dependencies are in the classpath        │
│                                                                   │
│ 📖 Documentation:                                                 │
│   https://docs.spring-actor.io/troubleshooting#bean-not-found    │
│                                                                   │
│ 🎯 Actor Context:                                                 │
│   - Actor Path: /user/order-actor                               │
│   - Actor Class: OrderActor                                     │
╰───────────────────────────────────────────────────────────────────╯

Testing

56 tests for error framework (detection, formatting, hint substitution, integration scenarios)
All 190 core tests passing

Dependencies

Added org.yaml:snakeyaml for hint database parsing

Additional Context

Non-breaking additive change. Existing exception handling unchanged. Framework can be adopted incrementally as needed. See core/src/main/java/io/github/seonwkim/core/error/README.md for full usage guide.

Original prompt

You are tasked with implementing enhanced developer experience features for the spring-boot-starter-actor project.

REPOSITORY INFORMATION:

Branch: main (you MUST work on main branch)

Directory: roadmap/8-developer-experience/

PRIORITY: HIGH (Error messages have massive DX impact) EFFORT: 1-2 weeks (Phase 1 only - highest priority)

OBJECTIVE: Create context-aware error messages with troubleshooting hints and documentation links to dramatically improve developer experience.

TASKS: Read all files in roadmap/8-developer-experience/ first.

PHASE 1 (Week 1-2): Enhanced Error Messages - HIGH PRIORITY

Read tasks/01-error-message-framework.md for detailed specifications

Create structured error message framework with categories:

Configuration errors (invalid YAML, missing beans, etc.)

Messaging errors (dead letters, unhandled messages, ask timeouts)

Lifecycle errors (actor creation failures, restart loops, etc.)

Clustering errors (split brain, unreachable members, etc.)

Build database of common error scenarios with troubleshooting hints

For each common error, provide:

Clear description of what went wrong

Likely causes

Actionable troubleshooting steps

Documentation links for more information

Read tasks/02-error-formatting.md

Implement pretty-print formatting for error output

Enhance stack traces with actor context:

Actor path

Message type being processed

Actor state information

Related actors involved

Create error detection patterns for common mistakes

Implement error categorization logic

Write comprehensive tests for error message framework

COMMON ERROR SCENARIOS TO HANDLE:

Configuration Errors:

Missing @EnableActorSystem annotation

Invalid port configuration for clustering

Incorrect actor reference format

Missing required beans

Messaging Errors:

Ask timeout with no response

Dead letters (message sent to stopped actor)

Unhandled message type

Serialization failures

Lifecycle Errors:

Actor creation failures (exception in constructor)

Restart loop (actor failing repeatedly)

Supervision strategy issues

Clustering Errors:

Node unreachable

Split brain scenario

Cluster formation failures

Sharding region not started

ERROR MESSAGE FORMAT: Each error should follow this structure:
[ERROR CATEGORY] Error Description

What Happened:
  Clear explanation of the error

Likely Cause:
  Most common reasons for this error

How to Fix:
  1. Step-by-step troubleshooting instructions
  2. With specific examples
  3. And configuration snippets if applicable

Related Documentation:
  https://docs.example.com/relevant-section

Actor Context:
  - Actor Path: /user/myActor
  - Message Type: MyMessage
  - Actor State: RUNNING
PHASE 2 (Optional, Deferred): Visualization Tool

Read tasks/03-actor-visualization.md

This phase is OPTIONAL and LOW priority

Only implement if Phase 1 is complete and time permits

Actor hierarchy visualization via web UI

Real-time updates

CRITICAL IMPLEMENTATION NOTES:

Focus on error messages that developers actually encounter

Provide actionable guidance, not just descriptions

Include links to relevant documentation

Make stack traces readable and contextual

Test error messages with real scenarios

WHAT NOT TO DO:

DO NOT implement Hot Reload Support (removed feature)

DO NOT spend time on visualization tools initially (defer to Phase 2)

SUCCESS CRITERIA:

Error messages include actionable troubleshooting steps

Common errors are detected and categorized automatically

Documentation links are provided in error messages

Stack traces include actor context information

Developer satisfaction is significantly improved

Error messages are tested with real error scenarios

IMPLEMENTATION APPROACH: Create a centralized error handling framework that intercepts common error scenarios and enhances them with context and troubleshooting guidance.

START BY:

Checking out the main branch

Reading all files in roadmap/8-developer-experience/

Reading tasks/TASK_PRIORITY.md to understand the implementation order

Starting with Phase 1: Error message framework

Identifying the most common error scenarios from existing codebase

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Nov 08 '25 21:11 Copilot