This guide covers common issues you might encounter when integrating Metorial with the AI SDK and how to resolve them.

Authentication Errors

"Invalid API key"

Cause: Your Metorial API key is incorrect or missing.

Solution:

// Check that your key is properly loaded
console.log('API Key exists:', !!process.env.METORIAL_API_KEY);

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

Verify:

• The key is correctly set in your .env.local file
• You've restarted your development server after adding the key
• There are no extra spaces or quotes around the key

"Invalid server deployment ID"

Cause: The deployment ID doesn't exist or you don't have access to it.

Solution:

• Log in to your Metorial dashboard
• Navigate to Server Deployments
• Copy the correct deployment ID
• Verify it matches what's in your code

Session Errors

"Session already closed"

Cause: Trying to use a session after the withProviderSession callback has completed.

Solution:

// ❌ Don't do this
let savedSession;
await metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: ['dep_123'] },
  async session => {
    savedSession = session; // Don't save for later use
  }
);
savedSession.callTools(...); // This will fail

// ✅ Do this instead
await metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: ['dep_123'] },
  async session => {
    // Do all your work inside the callback
    await session.callTools(...);
  }
);

Tool Call Errors

"Tool not found"

Cause: The AI model is trying to call a tool that isn't in your server deployment.

Solution:

• Check your server deployment in the Metorial dashboard
• Verify it includes the integration the tool needs
• Update your deployment to include missing integrations

"Tool execution timeout"

Cause: A tool call is taking too long to complete.

Solution:

try {
  const result = await generateText({
    model: openai('gpt-4'),
    messages,
    tools: session.tools,
    maxToolRoundtrips: 5
  });
} catch (error) {
  if (error.message.includes('timeout')) {
    console.error('Tool execution timed out');
    // Implement retry logic or fallback
  }
}

Model Errors

"Rate limit exceeded"

Cause: You've exceeded your AI provider's rate limits.

Solution:

• Implement exponential backoff retry logic
• Reduce the frequency of requests
• Upgrade your AI provider plan if needed

"Invalid model name"

Cause: The model identifier is incorrect for your AI provider.

Solution:

// For OpenAI
import { openai } from '@ai-sdk/openai';
const model = openai('gpt-4'); // Correct

// For Anthropic
import { anthropic } from '@ai-sdk/anthropic';
const model = anthropic('claude-3-opus-20240229'); // Correct

Check your AI provider's documentation for valid model names.

Network Errors

"Connection timeout"

Cause: Network connectivity issues or slow responses.

Solution:

// Implement retry logic
async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

await withRetry(() => 
  metorial.withProviderSession(/* ... */)
);

Debugging Tips

1. Enable verbose logging:

// Check tool calls during development
const result = await generateText({
  model: openai('gpt-4'),
  messages,
  tools: session.tools,
  onToolCall: (toolCall) => {
    console.log('Tool called:', toolCall);
  }
});

2. Check network requests: Use your browser's developer tools or a tool like Postman to verify API calls

3. Verify permissions: Ensure your API keys have the necessary permissions

4. Check service status: Visit Metorial's status page if you suspect a service issue

Getting Help

If you're still experiencing issues:

• Check the Metorial documentation
• Join our Discord community
• Contact support at [email protected] with:
  • Error messages
  • Relevant code snippets (remove API keys!)
  • Steps to reproduce the issue