This guide covers common issues when using Metorial with the AI SDK and how to resolve them.

Authentication Errors

Problem: "Invalid API Key"

Solution: Check that your Metorial API key is correct:

// Make sure you're loading from environment variables
const metorial = new Metorial({
  apiKey: process.env.METORIAL_API_KEY
});

// Verify the key is loaded
if (!process.env.METORIAL_API_KEY) {
  throw new Error('METORIAL_API_KEY not found');
}

Problem: "Unauthorized" or "Forbidden"

Solution: Your API key may have expired or been revoked. Generate a new one in your Metorial dashboard.

Server Deployment Issues

Problem: "Server deployment not found"

Solution: Verify your deployment ID is correct:

1. Check the Metorial dashboard for the correct deployment ID
2. Ensure you're using the ID as a string in an array:

serverDeployments: ['abc-123-def'] // Correct
// Not: serverDeployments: 'abc-123-def' // Wrong

Problem: "No tools available"

Solution: Your server deployment may be empty:

1. Log into the Metorial dashboard
2. Open your deployment
3. Add the integrations you need
4. Save the deployment

Tool Execution Errors

Problem: Tools are called but return errors

Solution: Check integration authentication:

1. Some integrations require OAuth authorization
2. Visit your Metorial dashboard
3. Authorize the required integrations
4. Retry the request

Problem: "Tool not found"

Solution: The integration may not be in your deployment:

// Log available tools to debug
await metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: ['your-deployment-id'] },
  async session => {
    console.log('Available tools:', session.tools.map(t => t.function.name));
  }
);

Model Issues

Problem: Model doesn't call tools

Solution:

• Increase maxSteps parameter
• Make your prompt more specific about what tools to use
• Verify the model supports function calling
• Try a different model (GPT-4 or Claude 3.5 Sonnet work well)

Problem: "Maximum steps reached"

Solution: The task is too complex for the current maxSteps limit:

maxSteps: 20 // Increase for more complex tasks

Or break the task into smaller subtasks.

Performance Issues

Problem: Slow response times

Solution:

• Reduce the number of tools in your deployment
• Use a faster model for simpler tasks
• Implement caching for frequently used data
• Consider streaming for better perceived performance

Network Errors

Problem: Connection timeouts

Solution:

• Check your internet connection
• Verify Metorial's service status
• Implement retry logic:

let retries = 3;
while (retries > 0) {
  try {
    const result = await generateText({...});
    break;
  } catch (error) {
    retries--;
    if (retries === 0) throw error;
    await new Promise(r => setTimeout(r, 1000));
  }
}

Getting Help

If you're still experiencing issues:

1. Check the Metorial documentation
2. Review the AI SDK documentation
3. Contact Metorial support with:
   • Your deployment ID
   • Error messages
   • Code snippets (remove API keys!)
   • Steps to reproduce the issue