Common issues when using Metorial with AI SDK and how to resolve them.

Common Issues

API Key Issues

Problem: "Invalid API key" or authentication errors

Solutions:

• Verify your API key is correct and not expired
• Check that the key is properly set in environment variables
• Ensure there are no extra spaces or quotes around the key
• Try creating a new API key in the Metorial dashboard

Deployment Not Found

Problem: "Server deployment not found" error

Solutions:

• Verify the deployment ID is correct
• Check that the deployment exists in your Metorial dashboard
• Ensure the deployment is active (not disabled)
• Confirm you're using the right account/workspace

No Tools Available

Problem: session.tools is empty or undefined

Solutions:

• Verify your deployment has integrations configured
• Check that integrations are properly authenticated
• Ensure the deployment ID is correctly passed to withProviderSession
• Review deployment settings in the Metorial dashboard

Tool Execution Failures

Problem: Tools are called but fail to execute

Solutions:

• Check integration authentication (OAuth tokens may be expired)
• Verify required permissions are granted for each integration
• Review tool parameters being passed by the model
• Check Metorial dashboard for integration-specific error messages

Debugging Techniques

Enable Verbose Logging

Log session details to understand what's happening:

await metorial.withProviderSession(
  metorialAISDK,
  { serverDeployments: ['your-deployment-id'] },
  async (session) => {
    console.log('Available tools:', session.tools.map(t => t.name));
    
    const result = await generateText({
      model: yourModel,
      messages: [...],
      tools: session.tools
    });
    
    console.log('Steps taken:', result.steps);
    console.log('Tool results:', result.toolResults);
  }
);

Inspect Tool Calls

Check which tools were called and their results:

const result = await generateText({
  model: yourModel,
  messages: [...],
  tools: session.tools
});

result.toolCalls?.forEach((call, i) => {
  console.log(`Tool ${i}:`, call.toolName);
  console.log('Arguments:', call.args);
});

result.toolResults?.forEach((result, i) => {
  console.log(`Result ${i}:`, result.result);
});

Test Deployments

Verify your deployment is working:

await metorial.withProviderSession(
  metorialAISDK,
  { serverDeployments: ['your-deployment-id'] },
  async (session) => {
    if (session.tools.length === 0) {
      console.error('No tools available in deployment');
      return;
    }
    
    console.log('Deployment is healthy');
    console.log('Available integrations:', session.tools.length);
  }
);

Performance Issues

Slow Response Times

If responses are taking too long:

• Reduce maxSteps to limit tool iterations
• Use more specific prompts to reduce unnecessary tool calls
• Check if specific integrations are slow (review logs)
• Consider caching frequently accessed data

Rate Limiting

If you hit rate limits:

• Implement exponential backoff for retries
• Reduce the frequency of requests
• Upgrade your Metorial plan if needed
• Optimize prompts to require fewer tool calls

Getting Help

If you're still experiencing issues:

1. Check the Metorial documentation
2. Review error messages in the Metorial dashboard
3. Search the community forum
4. Contact support with:
   • Error messages
   • Deployment ID
   • Code snippet (without API keys)
   • What you've tried already

Error Handling Best Practices

Always implement proper error handling:

try {
  await metorial.withProviderSession(
    metorialAISDK,
    { serverDeployments: ['your-deployment-id'] },
    async (session) => {
      try {
        const result = await generateText({
          model: yourModel,
          messages: [...],
          tools: session.tools
        });
        
        return result.text;
      } catch (modelError) {
        console.error('Model generation error:', modelError);
        throw modelError;
      }
    }
  );
} catch (sessionError) {
  console.error('Session error:', sessionError);
  // Handle gracefully for your users
}

This ensures you catch both session-level and model-level errors appropriately.