HashPilot

Instructions

Implementation Reference

• src/tools/error-analysis.ts:59-190 (handler)

  The primary handler function executing the 'error_explain' tool logic. It handles error code lookups, message analysis, category listings, keyword searches, and provides debugging guidance using the Hedera error database.

  export async function errorExplain(args: {
    errorCode?: string;
    errorMessage?: string;
    category?: ErrorInfo['category'];
    search?: string;
  }): Promise<{ success: boolean; data?: any; error?: string }> {
    try {
      // If category specified, list all errors in that category
      if (args.category) {
        const categoryErrors = getErrorsByCategory(args.category);
        return {
          success: true,
          data: {
            category: args.category,
            errorCount: categoryErrors.length,
            errors: categoryErrors.map((e) => ({
              code: e.code,
              name: e.name,
              description: e.description,
              solution: e.solution,
            })),
          },
        };
      }
  
      // If search specified, search errors by keyword
      if (args.search) {
        const results = searchErrors(args.search);
        return {
          success: true,
          data: {
            searchTerm: args.search,
            resultCount: results.length,
            results: results.map((e) => ({
              code: e.code,
              name: e.name,
              description: e.description,
              solution: e.solution,
            })),
          },
        };
      }
  
      // If error message provided, analyze it
      if (args.errorMessage) {
        const analysis = analyzeError(args.errorMessage);
        return {
          success: true,
          data: {
            originalError: analysis.originalError,
            detectedCode: analysis.errorCode,
            severity: analysis.severity,
            explanation: analysis.errorInfo
              ? {
                  name: analysis.errorInfo.name,
                  description: analysis.errorInfo.description,
                  cause: analysis.errorInfo.cause,
                  solution: analysis.errorInfo.solution,
                  category: analysis.errorInfo.category,
                }
              : null,
            guidance: analysis.guidance,
            securityRecommendations: analysis.securityRecommendations,
            optimizationSuggestions: analysis.optimizationSuggestions,
            relatedErrors: analysis.relatedErrors,
          },
        };
      }
  
      // If error code provided, look it up directly
      if (args.errorCode) {
        const errorInfo = getErrorInfo(args.errorCode);
  
        if (!errorInfo) {
          // Try to find similar errors
          const similar = searchErrors(args.errorCode);
          return {
            success: false,
            error: `Error code "${args.errorCode}" not found in database.`,
            data: {
              suggestion: 'Try one of these similar errors:',
              similarErrors: similar.slice(0, 5).map((e) => e.code),
              availableCategories: ['account', 'token', 'contract', 'consensus', 'network', 'transaction', 'key'],
            },
          };
        }
  
        return {
          success: true,
          data: {
            code: errorInfo.code,
            name: errorInfo.name,
            description: errorInfo.description,
            cause: errorInfo.cause,
            solution: errorInfo.solution,
            category: errorInfo.category,
            relatedErrors: getErrorsByCategory(errorInfo.category)
              .filter((e) => e.code !== errorInfo.code)
              .slice(0, 3)
              .map((e) => e.code),
          },
        };
      }
  
      // No input provided - return available error codes summary
      const categories = ['account', 'token', 'contract', 'consensus', 'network', 'transaction', 'key'] as const;
      const summary = categories.map((cat) => ({
        category: cat,
        count: getErrorsByCategory(cat).length,
      }));
  
      return {
        success: true,
        data: {
          message: 'Provide an errorCode, errorMessage, category, or search term',
          totalErrorCodes: Object.keys(HEDERA_ERROR_CODES).length,
          categorySummary: summary,
          exampleUsage: [
            { errorCode: 'INSUFFICIENT_PAYER_BALANCE' },
            { errorMessage: 'Status: TOKEN_NOT_ASSOCIATED_TO_ACCOUNT' },
            { category: 'token' },
            { search: 'balance' },
          ],
        },
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Failed to analyze error',
      };
    }
  }

• src/tools/error-analysis.ts:18-54 (schema)

  The tool definition object containing the name 'error_explain', detailed description, usage examples, and input schema for parameter validation.

  export const errorAnalysisToolDefinition = {
    name: 'error_explain',
    description: `Explain Hedera error codes and provide debugging guidance.
  
  USE FOR:
  - Understanding cryptic Hedera error codes (e.g., INSUFFICIENT_PAYER_BALANCE)
  - Getting step-by-step solutions for common errors
  - Finding related errors and security recommendations
  
  EXAMPLES:
  - "What does INSUFFICIENT_PAYER_BALANCE mean?"
  - "Explain TOKEN_NOT_ASSOCIATED_TO_ACCOUNT error"
  - "I got CONTRACT_REVERT_EXECUTED - what's wrong?"
  - "List all token-related errors"`,
    inputSchema: {
      type: 'object',
      properties: {
        errorCode: {
          type: 'string',
          description: 'Hedera error code to explain (e.g., INSUFFICIENT_PAYER_BALANCE, TOKEN_NOT_ASSOCIATED_TO_ACCOUNT)',
        },
        errorMessage: {
          type: 'string',
          description: 'Full error message to analyze (will extract error code automatically)',
        },
        category: {
          type: 'string',
          enum: ['account', 'token', 'contract', 'consensus', 'network', 'transaction', 'key', 'file'],
          description: 'List all errors in a specific category',
        },
        search: {
          type: 'string',
          description: 'Search errors by keyword',
        },
      },
    },
  };

• src/index.ts:529-531 (registration)

  Registration of the error_explain tool by including its definition in the optimizedToolDefinitions array, which is returned by ListToolsRequestSchema handler.

    // Error Analysis (1 tool - 50+ error codes with debugging guidance)
    errorAnalysisToolDefinition,
  ];

• src/index.ts:665-668 (registration)

  Dispatch registration in the main tool execution switch statement, mapping 'error_explain' calls to the errorExplain handler function.

  // Error Analysis
  case 'error_explain':
    result = await errorExplain(args as any);
    break;