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>
2026-02-06 05:23:08 +00:00 · 2025-10-01 10:57:29 +02:00
parent f4dff6b8e1
commit 64b9cf47a7
9 changed files with 450 additions and 11 deletions
--- a/tests/unit/mcp/handlers-n8n-manager.test.ts
+++ b/tests/unit/mcp/handlers-n8n-manager.test.ts
@@ -542,7 +542,7 @@ describe('handlers-n8n-manager', () => {

      expect(result).toEqual({
        success: false,
-        error: 'n8n server error. Please try again later or contact support.',
+        error: 'Service unavailable',
        code: 'SERVER_ERROR',
        details: {
          apiUrl: 'https://n8n.test.com',
@@ -642,4 +642,179 @@ describe('handlers-n8n-manager', () => {
      });
    });
  });
+
+  describe('handleTriggerWebhookWorkflow', () => {
+    it('should trigger webhook successfully', async () => {
+      const webhookResponse = {
+        status: 200,
+        statusText: 'OK',
+        data: { result: 'success' },
+        headers: {}
+      };
+
+      mockApiClient.triggerWebhook.mockResolvedValue(webhookResponse);
+
+      const result = await handlers.handleTriggerWebhookWorkflow({
+        webhookUrl: 'https://n8n.test.com/webhook/test-123',
+        httpMethod: 'POST',
+        data: { test: 'data' }
+      });
+
+      expect(result).toEqual({
+        success: true,
+        data: webhookResponse,
+        message: 'Webhook triggered successfully'
+      });
+    });
+
+    it('should extract execution ID from webhook error response', async () => {
+      const apiError = new N8nServerError('Workflow execution failed');
+      apiError.details = {
+        executionId: 'exec_abc123',
+        workflowId: 'wf_xyz789'
+      };
+
+      mockApiClient.triggerWebhook.mockRejectedValue(apiError);
+
+      const result = await handlers.handleTriggerWebhookWorkflow({
+        webhookUrl: 'https://n8n.test.com/webhook/test-123',
+        httpMethod: 'POST'
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Workflow wf_xyz789 execution exec_abc123 failed');
+      expect(result.error).toContain('n8n_get_execution');
+      expect(result.error).toContain("mode: 'preview'");
+      expect(result.executionId).toBe('exec_abc123');
+      expect(result.workflowId).toBe('wf_xyz789');
+    });
+
+    it('should extract execution ID without workflow ID', async () => {
+      const apiError = new N8nServerError('Execution failed');
+      apiError.details = {
+        executionId: 'exec_only_123'
+      };
+
+      mockApiClient.triggerWebhook.mockRejectedValue(apiError);
+
+      const result = await handlers.handleTriggerWebhookWorkflow({
+        webhookUrl: 'https://n8n.test.com/webhook/test-123',
+        httpMethod: 'GET'
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Execution exec_only_123 failed');
+      expect(result.error).toContain('n8n_get_execution');
+      expect(result.error).toContain("mode: 'preview'");
+      expect(result.executionId).toBe('exec_only_123');
+      expect(result.workflowId).toBeUndefined();
+    });
+
+    it('should handle execution ID as "id" field', async () => {
+      const apiError = new N8nServerError('Error');
+      apiError.details = {
+        id: 'exec_from_id_field',
+        workflowId: 'wf_test'
+      };
+
+      mockApiClient.triggerWebhook.mockRejectedValue(apiError);
+
+      const result = await handlers.handleTriggerWebhookWorkflow({
+        webhookUrl: 'https://n8n.test.com/webhook/test',
+        httpMethod: 'POST'
+      });
+
+      expect(result.error).toContain('exec_from_id_field');
+      expect(result.executionId).toBe('exec_from_id_field');
+    });
+
+    it('should provide generic guidance when no execution ID is available', async () => {
+      const apiError = new N8nServerError('Server error without execution context');
+      apiError.details = {}; // No execution ID
+
+      mockApiClient.triggerWebhook.mockRejectedValue(apiError);
+
+      const result = await handlers.handleTriggerWebhookWorkflow({
+        webhookUrl: 'https://n8n.test.com/webhook/test',
+        httpMethod: 'POST'
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Workflow failed to execute');
+      expect(result.error).toContain('n8n_list_executions');
+      expect(result.error).toContain('n8n_get_execution');
+      expect(result.error).toContain("mode='preview'");
+      expect(result.executionId).toBeUndefined();
+    });
+
+    it('should use standard error message for authentication errors', async () => {
+      const authError = new N8nAuthenticationError('Invalid API key');
+      mockApiClient.triggerWebhook.mockRejectedValue(authError);
+
+      const result = await handlers.handleTriggerWebhookWorkflow({
+        webhookUrl: 'https://n8n.test.com/webhook/test',
+        httpMethod: 'POST'
+      });
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Failed to authenticate with n8n. Please check your API key.',
+        code: 'AUTHENTICATION_ERROR',
+        details: undefined
+      });
+    });
+
+    it('should use standard error message for validation errors', async () => {
+      const validationError = new N8nValidationError('Invalid webhook URL');
+      mockApiClient.triggerWebhook.mockRejectedValue(validationError);
+
+      const result = await handlers.handleTriggerWebhookWorkflow({
+        webhookUrl: 'https://n8n.test.com/webhook/test',
+        httpMethod: 'POST'
+      });
+
+      expect(result.error).toBe('Invalid request: Invalid webhook URL');
+      expect(result.code).toBe('VALIDATION_ERROR');
+    });
+
+    it('should handle invalid input with Zod validation error', async () => {
+      const result = await handlers.handleTriggerWebhookWorkflow({
+        webhookUrl: 'not-a-url',
+        httpMethod: 'INVALID_METHOD'
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Invalid input');
+      expect(result.details).toHaveProperty('errors');
+    });
+
+    it('should not include "contact support" in error messages', async () => {
+      const apiError = new N8nServerError('Test error');
+      apiError.details = { executionId: 'test_exec' };
+
+      mockApiClient.triggerWebhook.mockRejectedValue(apiError);
+
+      const result = await handlers.handleTriggerWebhookWorkflow({
+        webhookUrl: 'https://n8n.test.com/webhook/test',
+        httpMethod: 'POST'
+      });
+
+      expect(result.error?.toLowerCase()).not.toContain('contact support');
+      expect(result.error?.toLowerCase()).not.toContain('try again later');
+    });
+
+    it('should always recommend preview mode in error messages', async () => {
+      const apiError = new N8nServerError('Error');
+      apiError.details = { executionId: 'test_123' };
+
+      mockApiClient.triggerWebhook.mockRejectedValue(apiError);
+
+      const result = await handlers.handleTriggerWebhookWorkflow({
+        webhookUrl: 'https://n8n.test.com/webhook/test',
+        httpMethod: 'POST'
+      });
+
+      expect(result.error).toMatch(/mode:\s*'preview'/);
+    });
+  });
 });
--- a/tests/unit/utils/n8n-errors.test.ts
+++ b/tests/unit/utils/n8n-errors.test.ts
@@ -0,0 +1,171 @@
+import { describe, it, expect } from 'vitest';
+import {
+  formatExecutionError,
+  formatNoExecutionError,
+  getUserFriendlyErrorMessage,
+  N8nApiError,
+  N8nAuthenticationError,
+  N8nNotFoundError,
+  N8nValidationError,
+  N8nRateLimitError,
+  N8nServerError
+} from '../../../src/utils/n8n-errors';
+
+describe('formatExecutionError', () => {
+  it('should format error with both execution ID and workflow ID', () => {
+    const result = formatExecutionError('exec_12345', 'wf_abc');
+
+    expect(result).toBe("Workflow wf_abc execution exec_12345 failed. Use n8n_get_execution({id: 'exec_12345', mode: 'preview'}) to investigate the error.");
+    expect(result).toContain('mode: \'preview\'');
+    expect(result).toContain('exec_12345');
+    expect(result).toContain('wf_abc');
+  });
+
+  it('should format error with only execution ID', () => {
+    const result = formatExecutionError('exec_67890');
+
+    expect(result).toBe("Execution exec_67890 failed. Use n8n_get_execution({id: 'exec_67890', mode: 'preview'}) to investigate the error.");
+    expect(result).toContain('mode: \'preview\'');
+    expect(result).toContain('exec_67890');
+    expect(result).not.toContain('Workflow');
+  });
+
+  it('should include preview mode guidance', () => {
+    const result = formatExecutionError('test_id');
+
+    expect(result).toMatch(/mode:\s*'preview'/);
+  });
+
+  it('should format with undefined workflow ID (treated as missing)', () => {
+    const result = formatExecutionError('exec_123', undefined);
+
+    expect(result).toBe("Execution exec_123 failed. Use n8n_get_execution({id: 'exec_123', mode: 'preview'}) to investigate the error.");
+  });
+
+  it('should properly escape execution ID in suggestion', () => {
+    const result = formatExecutionError('exec-with-special_chars.123');
+
+    expect(result).toContain("id: 'exec-with-special_chars.123'");
+  });
+});
+
+describe('formatNoExecutionError', () => {
+  it('should provide guidance to check recent executions', () => {
+    const result = formatNoExecutionError();
+
+    expect(result).toBe("Workflow failed to execute. Use n8n_list_executions to find recent executions, then n8n_get_execution with mode='preview' to investigate.");
+    expect(result).toContain('n8n_list_executions');
+    expect(result).toContain('n8n_get_execution');
+    expect(result).toContain("mode='preview'");
+  });
+
+  it('should include preview mode in guidance', () => {
+    const result = formatNoExecutionError();
+
+    expect(result).toMatch(/mode\s*=\s*'preview'/);
+  });
+});
+
+describe('getUserFriendlyErrorMessage', () => {
+  it('should handle authentication error', () => {
+    const error = new N8nAuthenticationError('Invalid API key');
+    const message = getUserFriendlyErrorMessage(error);
+
+    expect(message).toBe('Failed to authenticate with n8n. Please check your API key.');
+  });
+
+  it('should handle not found error', () => {
+    const error = new N8nNotFoundError('Workflow', '123');
+    const message = getUserFriendlyErrorMessage(error);
+
+    expect(message).toContain('not found');
+  });
+
+  it('should handle validation error', () => {
+    const error = new N8nValidationError('Missing required field');
+    const message = getUserFriendlyErrorMessage(error);
+
+    expect(message).toBe('Invalid request: Missing required field');
+  });
+
+  it('should handle rate limit error', () => {
+    const error = new N8nRateLimitError(60);
+    const message = getUserFriendlyErrorMessage(error);
+
+    expect(message).toBe('Too many requests. Please wait a moment and try again.');
+  });
+
+  it('should handle server error with custom message', () => {
+    const error = new N8nServerError('Database connection failed', 503);
+    const message = getUserFriendlyErrorMessage(error);
+
+    expect(message).toBe('Database connection failed');
+  });
+
+  it('should handle server error without message', () => {
+    const error = new N8nApiError('', 500, 'SERVER_ERROR');
+    const message = getUserFriendlyErrorMessage(error);
+
+    expect(message).toBe('n8n server error occurred');
+  });
+
+  it('should handle no response error', () => {
+    const error = new N8nApiError('Network error', undefined, 'NO_RESPONSE');
+    const message = getUserFriendlyErrorMessage(error);
+
+    expect(message).toBe('Unable to connect to n8n. Please check the server URL and ensure n8n is running.');
+  });
+
+  it('should handle unknown error with message', () => {
+    const error = new N8nApiError('Custom error message');
+    const message = getUserFriendlyErrorMessage(error);
+
+    expect(message).toBe('Custom error message');
+  });
+
+  it('should handle unknown error without message', () => {
+    const error = new N8nApiError('');
+    const message = getUserFriendlyErrorMessage(error);
+
+    expect(message).toBe('An unexpected error occurred');
+  });
+});
+
+describe('Error message integration', () => {
+  it('should use formatExecutionError for webhook failures with execution ID', () => {
+    const executionId = 'exec_webhook_123';
+    const workflowId = 'wf_webhook_abc';
+    const message = formatExecutionError(executionId, workflowId);
+
+    expect(message).toContain('Workflow wf_webhook_abc execution exec_webhook_123 failed');
+    expect(message).toContain('n8n_get_execution');
+    expect(message).toContain("mode: 'preview'");
+  });
+
+  it('should use formatNoExecutionError for server errors without execution context', () => {
+    const message = formatNoExecutionError();
+
+    expect(message).toContain('Workflow failed to execute');
+    expect(message).toContain('n8n_list_executions');
+    expect(message).toContain('n8n_get_execution');
+  });
+
+  it('should not include "contact support" in any error message', () => {
+    const executionMessage = formatExecutionError('test');
+    const noExecutionMessage = formatNoExecutionError();
+    const serverError = new N8nServerError();
+    const serverErrorMessage = getUserFriendlyErrorMessage(serverError);
+
+    expect(executionMessage.toLowerCase()).not.toContain('contact support');
+    expect(noExecutionMessage.toLowerCase()).not.toContain('contact support');
+    expect(serverErrorMessage.toLowerCase()).not.toContain('contact support');
+  });
+
+  it('should always guide users to use preview mode first', () => {
+    const executionMessage = formatExecutionError('test');
+    const noExecutionMessage = formatNoExecutionError();
+
+    expect(executionMessage).toContain("mode: 'preview'");
+    expect(noExecutionMessage).toContain("mode='preview'");
+  });
+});