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

@@ -18,7 +18,9 @@ import {
import {
N8nApiError,
N8nNotFoundError,
getUserFriendlyErrorMessage
getUserFriendlyErrorMessage,
formatExecutionError,
formatNoExecutionError
} from '../utils/n8n-errors';
import { logger } from '../utils/logger';
import { z } from 'zod';
@@ -942,7 +944,7 @@ export async function handleTriggerWebhookWorkflow(args: unknown, context?: Inst
try {
const client = ensureApiConfigured(context);
const input = triggerWebhookSchema.parse(args);
const webhookRequest: WebhookRequest = {
webhookUrl: input.webhookUrl,
httpMethod: input.httpMethod || 'POST',
@@ -950,9 +952,9 @@ export async function handleTriggerWebhookWorkflow(args: unknown, context?: Inst
headers: input.headers,
waitForResponse: input.waitForResponse ?? true
};
const response = await client.triggerWebhook(webhookRequest);
return {
success: true,
data: response,
@@ -966,8 +968,35 @@ export async function handleTriggerWebhookWorkflow(args: unknown, context?: Inst
details: { errors: error.errors }
};
}
if (error instanceof N8nApiError) {
// Try to extract execution context from error response
const errorData = error.details as any;
const executionId = errorData?.executionId || errorData?.id || errorData?.execution?.id;
const workflowId = errorData?.workflowId || errorData?.workflow?.id;
// If we have execution ID, provide specific guidance with n8n_get_execution
if (executionId) {
return {
success: false,
error: formatExecutionError(executionId, workflowId),
code: error.code,
executionId,
workflowId: workflowId || undefined
};
}
// No execution ID available - workflow likely didn't start
// Provide guidance to check recent executions
if (error.code === 'SERVER_ERROR' || error.statusCode && error.statusCode >= 500) {
return {
success: false,
error: formatNoExecutionError(),
code: error.code
};
}
// For other errors (auth, validation, etc), use standard message
return {
success: false,
error: getUserFriendlyErrorMessage(error),
@@ -975,7 +1004,7 @@ export async function handleTriggerWebhookWorkflow(args: unknown, context?: Inst
details: error.details as Record<string, unknown> | undefined
};
}
return {
success: false,
error: error instanceof Error ? error.message : 'Unknown error occurred'