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

Common Errors

Invalid API Key

try {
  const metorial = new Metorial({
    apiKey: 'invalid-key'
  });
  
  await metorial.withProviderSession(
    metorialAiSdk,
    { serverDeployments: ['deployment-id'] },
    async session => {
      // ...
    }
  );
} catch (error) {
  if (error.message.includes('Invalid API key')) {
    console.error('Please check your Metorial API key');
  }
}

Invalid Server Deployment

If you reference a deployment ID that doesn't exist:

try {
  await metorial.withProviderSession(
    metorialAiSdk,
    { serverDeployments: ['non-existent-deployment'] },
    async session => {
      // ...
    }
  );
} catch (error) {
  console.error('Deployment not found:', error.message);
}

Debugging Tool Calls

To see what tools are available in your session:

await metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: ['your-deployment-id'] },
  async session => {
    console.log('Available tools:', session.tools.length);
    console.log('Tool names:', session.tools.map(t => t.name));
    
    // Your AI SDK code
  }
);

Logging AI SDK Responses

To debug the full conversation flow:

import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-4'),
  tools: session.tools,
  prompt: 'Your prompt',
  onFinish: ({ response }) => {
    console.log('Full response:', JSON.stringify(response, null, 2));
  }
});

Environment Variables for Debugging

Set up environment variables for easier debugging:

# .env
METORIAL_API_KEY=your-key
METORIAL_DEPLOYMENT_ID=your-deployment-id
DEBUG=true

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

if (process.env.DEBUG === 'true') {
  console.log('Debug mode enabled');
}

Getting Help

If you encounter issues:

1. Check your API key is valid
2. Verify your server deployment ID exists
3. Ensure your integrations are properly configured
4. Review the Metorial documentation
5. Contact Metorial support with error logs