Learn how to handle errors and debug issues when using Metorial with the AI SDK.

Common Errors

Invalid API Key

Error: "Authentication failed" or "Invalid API key"

Solution: Check that your Metorial API key is correct and properly set:

// Make sure the key is loaded
console.log('API Key:', process.env.METORIAL_API_KEY ? 'Set' : 'Missing');

let metorial = new Metorial({ 
  apiKey: process.env.METORIAL_API_KEY 
});

Invalid Server Deployment

Error: "Server deployment not found" or "Invalid deployment ID"

Solution: Verify your deployment ID in the Metorial dashboard and ensure it's correctly passed:

metorial.withProviderSession(
  metorialAiSdk,
  {
    serverDeployments: ['correct-deployment-id']
  },
  async session => {
    // ...
  }
);

Max Steps Exceeded

Error: Task doesn't complete or stops unexpectedly

Solution: Increase maxSteps for complex tasks:

let result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Complex multi-step task',
  maxSteps: 20, // Increased from default
  tools: session.tools
});

Proper Error Handling

Always wrap your code in try-catch blocks:

metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: ['your-deployment'] },
  async session => {
    try {
      let result = await generateText({
        model: openai('gpt-4o'),
        prompt: 'Your prompt',
        maxSteps: 10,
        tools: session.tools
      });

      console.log('Success:', result.text);
    } catch (error) {
      console.error('Error during generation:', error);
      
      // Handle specific error types
      if (error.message.includes('API key')) {
        console.error('Check your API keys');
      } else if (error.message.includes('rate limit')) {
        console.error('Rate limit exceeded, try again later');
      }
    }
  }
);

Debugging Tips

Enable Verbose Logging

Check what tools are being called:

let result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Your prompt',
  maxSteps: 10,
  tools: session.tools
});

// Inspect the steps taken
if (result.steps) {
  console.log('Steps taken:', result.steps.length);
  result.steps.forEach((step, i) => {
    console.log(`Step ${i + 1}:`, step);
  });
}

Check Tool Availability

Verify that tools are loaded correctly:

metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: ['your-deployment'] },
  async session => {
    console.log('Available tools:', Object.keys(session.tools));
    
    // Continue with your logic
  }
);

Test with Simple Prompts

Start with simple queries to verify the setup:

// Simple test that shouldn't need tools
let test1 = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Say hello',
  maxSteps: 1,
  tools: session.tools
});

console.log('Basic test:', test1.text);

// Test that requires one tool call
let test2 = await generateText({
  model: openai('gpt-4o'),
  prompt: 'What time is it?',
  maxSteps: 3,
  tools: session.tools
});

console.log('Tool test:', test2.text);

Rate Limiting

If you're hitting rate limits:

1. Check your plan: Verify your Metorial plan limits
2. Implement backoff: Add retry logic with exponential backoff
3. Optimize calls: Reduce maxSteps or batch requests
4. Cache results: Store and reuse responses when appropriate

Getting Help

If you're still experiencing issues:

1. Check Documentation: Visit metorial.com/docs
2. Review Examples: Look at working examples in the repository
3. Contact Support: Reach out to Metorial support with error details
4. Community: Join the Metorial Discord or community forums

Debugging Checklist

• [ ] Environment variables are set correctly
• [ ] API keys are valid and not expired
• [ ] Server deployment ID is correct
• [ ] Required packages are installed
• [ ] AI provider API key is set
• [ ] Network connection is stable
• [ ] Rate limits haven't been exceeded
• [ ] Error handling is implemented