mirror of
https://github.com/czlonkowski/n8n-mcp.git
synced 2026-03-24 03:13:07 +00:00
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:
@@ -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';
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user