feat: enhance webhook error messages with execution guidance

Replace generic "Please try again later or contact support" error messages
with actionable guidance that directs users to use n8n_get_execution with
mode='preview' for efficient debugging.

## Changes

### Core Functionality
- Add formatExecutionError() to create execution-specific error messages
- Add formatNoExecutionError() for cases without execution context
- Update handleTriggerWebhookWorkflow to extract execution/workflow IDs from errors
- Modify getUserFriendlyErrorMessage to avoid generic SERVER_ERROR message

### Type Updates
- Add executionId and workflowId optional fields to McpToolResponse
- Add errorHandling optional field to ToolDocumentation.full

### Error Message Format

**With Execution ID:**
"Workflow {workflowId} execution {executionId} failed. Use n8n_get_execution({id: '{executionId}', mode: 'preview'}) to investigate the error."

**Without Execution ID:**
"Workflow failed to execute. Use n8n_list_executions to find recent executions, then n8n_get_execution with mode='preview' to investigate."

### Testing
- Add comprehensive tests in tests/unit/utils/n8n-errors.test.ts (20 tests)
- Add 10 new tests for handleTriggerWebhookWorkflow in handlers-n8n-manager.test.ts
- Update existing health check test to expect new error message format
- All tests passing (52 total tests)

### Documentation
- Update n8n-trigger-webhook-workflow tool documentation with errorHandling section
- Document why mode='preview' is recommended (fast, efficient, safe)
- Add example error responses and investigation workflow

## Why mode='preview'?
- Fast: <50ms response time
- Efficient: ~500 tokens (vs 50K+ for full mode)
- Safe: No timeout or token limit risks
- Informative: Shows structure, counts, and error details

## Breaking Changes
None - backward compatible improvement to error messages only.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
2025-10-01 10:57:29 +02:00
parent f4dff6b8e1
commit 64b9cf47a7
9 changed files with 450 additions and 11 deletions

View File

@@ -95,6 +95,25 @@ export function handleN8nApiError(error: unknown): N8nApiError {
return new N8nApiError('Unknown error occurred', undefined, 'UNKNOWN_ERROR', error);
}
/**
* Format execution error message with guidance to use n8n_get_execution
* @param executionId - The execution ID from the failed execution
* @param workflowId - Optional workflow ID
* @returns Formatted error message with n8n_get_execution guidance
*/
export function formatExecutionError(executionId: string, workflowId?: string): string {
const workflowPrefix = workflowId ? `Workflow ${workflowId} execution ` : 'Execution ';
return `${workflowPrefix}${executionId} failed. Use n8n_get_execution({id: '${executionId}', mode: 'preview'}) to investigate the error.`;
}
/**
* Format error message when no execution ID is available
* @returns Generic guidance to check executions
*/
export function formatNoExecutionError(): string {
return "Workflow failed to execute. Use n8n_list_executions to find recent executions, then n8n_get_execution with mode='preview' to investigate.";
}
// Utility to extract user-friendly error messages
export function getUserFriendlyErrorMessage(error: N8nApiError): string {
switch (error.code) {
@@ -109,7 +128,9 @@ export function getUserFriendlyErrorMessage(error: N8nApiError): string {
case 'NO_RESPONSE':
return 'Unable to connect to n8n. Please check the server URL and ensure n8n is running.';
case 'SERVER_ERROR':
return 'n8n server error. Please try again later or contact support.';
// For server errors, we should not show generic message
// Callers should check for execution context and use formatExecutionError instead
return error.message || 'n8n server error occurred';
default:
return error.message || 'An unexpected error occurred';
}