Errors

import { ArcadeMCP, NotFoundError } from 'arcade-mcp-server';
import { z } from 'zod';
 
const app = new ArcadeMCP({ name: 'user-service' });
 
app.tool('getUser', {
  input: z.object({ id: z.string() }),
  handler: async ({ input }) => {
    const user = await db.findUser(input.id);
    if (!user) {
      throw new NotFoundError(`User ${input.id} not found`);
    }
    return user;
  },
});

import { AuthorizationError } from 'arcade-mcp-server';
 
// In your tool handler:
if (project.ownerEmail !== userEmail) {
  throw new AuthorizationError('Only the owner can delete this project');
}

import { ResourceError } from 'arcade-mcp-server';
 
throw new ResourceError('Cannot read resource: config://settings');

import { PromptError } from 'arcade-mcp-server';
 
throw new PromptError('Prompt template not found: greeting');

import { RetryableToolError } from 'arcade-mcp-server';
 
// Simple retry
throw new RetryableToolError('Service temporarily unavailable');
 
// With retry delay
throw new RetryableToolError('Rate limited', {
  retryAfterMs: 5000,
});
 
// With guidance for the AI on how to retry differently
throw new RetryableToolError('Search returned no results', {
  additionalPromptContent: 'Try broader search terms or check spelling.',
});

import { FatalToolError } from 'arcade-mcp-server';
 
throw new FatalToolError('Account has been permanently deleted');
 
// With developer-only details (not shown to AI)
throw new FatalToolError('Configuration error', {
  developerMessage: 'Missing required API key in environment',
});

import { ContextRequiredToolError } from 'arcade-mcp-server';
 
throw new ContextRequiredToolError('Multiple users found matching "John"', {
  additionalPromptContent: 'Please specify: John Smith (john@work.com) or John Doe (john@home.com)',  // required
});

import { UpstreamError } from 'arcade-mcp-server';
 
throw new UpstreamError('Slack API error: channel_not_found', {
  statusCode: 404,  // required
});

import { UpstreamRateLimitError } from 'arcade-mcp-server';
 
throw new UpstreamRateLimitError('Rate limited by Slack', {
  retryAfterMs: 60_000,  // required — milliseconds until retry
});

// RetryableToolError — all options are optional
new RetryableToolError(message: string, options?: {
  developerMessage?: string;
  additionalPromptContent?: string;
  retryAfterMs?: number;
  extra?: Record<string, unknown>;
  cause?: unknown;
});
 
// FatalToolError — all options are optional
new FatalToolError(message: string, options?: {
  developerMessage?: string;
  extra?: Record<string, unknown>;
  cause?: unknown;
});
 
// ContextRequiredToolError — additionalPromptContent is REQUIRED
new ContextRequiredToolError(message: string, options: {
  additionalPromptContent: string;  // required
  developerMessage?: string;
  extra?: Record<string, unknown>;
  cause?: unknown;
});
 
// UpstreamError — statusCode is REQUIRED
new UpstreamError(message: string, options: {
  statusCode: number;  // required
  developerMessage?: string;
  extra?: Record<string, unknown>;
  cause?: unknown;
});
 
// UpstreamRateLimitError — retryAfterMs is REQUIRED
new UpstreamRateLimitError(message: string, options: {
  retryAfterMs: number;  // required
  developerMessage?: string;
  extra?: Record<string, unknown>;
  cause?: unknown;
});

MCPError (base)
├── MCPContextError (user/input caused the error)
│   ├── AuthorizationError
│   ├── NotFoundError
│   ├── PromptError
│   └── ResourceError
└── MCPRuntimeError (server/infrastructure caused the error)
    ├── ProtocolError
    ├── TransportError
    └── ServerError
        ├── RequestError
        │   └── ServerRequestError
        ├── ResponseError
        ├── SessionError
        └── LifespanError

ToolkitError (base for tool errors)
└── ToolError
    └── ToolRuntimeError
        ├── RetryableToolError (canRetry: true)
        ├── FatalToolError (canRetry: false)
        ├── ContextRequiredToolError (canRetry: false)
        └── UpstreamError (canRetry: true for 5xx/429)
            └── UpstreamRateLimitError (canRetry: true)

import { ErrorKind } from 'arcade-mcp-server';
 
// Example: log errors by kind
console.log(error.kind); // e.g., ErrorKind.TOOL_RUNTIME_RETRY

import { FatalToolError } from 'arcade-mcp-server';
 
class QuotaExceededError extends FatalToolError {
  readonly limitType: string;
 
  constructor(message: string, limitType: string) {
    super(message, { extra: { limitType } });
    this.name = 'QuotaExceededError';
    this.limitType = limitType;
  }
}
 
throw new QuotaExceededError('Monthly API quota exceeded', 'api_calls');

// ✅ Good: Specific error type
throw new NotFoundError('User not found');
 
// ✅ Good: Retryable with guidance
throw new RetryableToolError('Search returned no results', {
  additionalPromptContent: 'Try broader search terms.',
});

// ❌ Bad: Leaks implementation details
throw new Error(`Database error: ${dbError.stack}`);
 
// ❌ Bad: Leaks SQL
throw new Error(`Query failed: SELECT * FROM users WHERE...`);

// ❌ Vague
throw new RetryableToolError('Invalid input');
 
// ✅ Actionable with context
throw new RetryableToolError(`Invalid email: "${input.email}"`, {
  additionalPromptContent: 'Use format: user@domain.com',
});

import { RetryableToolError } from 'arcade-mcp-server';
 
// In your tool handler:
try {
  return await weatherApi.get(input.city);
} catch (error) {
  throw new RetryableToolError(
    `Failed to fetch weather for ${input.city}. Please try again.`,
    { cause: error }  // Preserves stack trace for debugging
  );
}

import { Middleware, MCPError, type MiddlewareContext, type CallNext } from 'arcade-mcp-server';
 
class ErrorLoggingMiddleware extends Middleware {
  async onCallTool(context: MiddlewareContext, next: CallNext) {
    try {
      return await next(context);
    } catch (error) {
      if (error instanceof MCPError) {
        console.error({ type: error.name, message: error.message });
      }
      throw error;  // Re-throw for ErrorHandlingMiddleware
    }
  }
}