Encountering problems with Google Gemini and Metorial? This guide covers common issues and their solutions.

Issue 1: "Invalid API Key" Error

Problem: You're getting authentication errors when initializing clients.

Solution:

• Verify your API keys are correct and complete
• Check that you haven't included extra spaces or newlines
• Ensure you're using the right environment variables

// ✅ Correct
let metorial = new Metorial({ 
  apiKey: process.env.METORIAL_API_KEY?.trim() 
});

// ❌ Wrong - key might have whitespace
let metorial = new Metorial({ 
  apiKey: process.env.METORIAL_API_KEY 
});

Issue 2: Function Calls Not Being Made

Problem: Gemini returns text instead of calling your Metorial integrations.

Solution:

• Verify you're passing session.tools in the config
• Make sure your prompt clearly indicates what action you want
• Check that your server deployment has the necessary integrations

// ✅ Correct - tools are passed
let response = await genAI.models.generateContent({
  model: 'gemini-1.5-pro-latest',
  contents: [/* ... */],
  config: {
    tools: session.tools  // Don't forget this!
  }
});

// ❌ Wrong - no tools provided
let response = await genAI.models.generateContent({
  model: 'gemini-1.5-pro-latest',
  contents: [/* ... */]
});

Issue 3: "Server Deployment Not Found"

Problem: Error saying your server deployment ID doesn't exist.

Solution:

• Double-check the deployment ID in your Metorial dashboard
• Ensure the deployment is active and not deleted
• Verify you're using the correct Metorial API key that has access to this deployment

await metorial.withProviderSession(
  metorialGoogle,
  { 
    serverDeployments: ['check-this-id-carefully'] 
  },
  async session => {
    // ...
  }
);

Issue 4: Function Calls Return Undefined

Problem: session.callTools() returns undefined or empty results.

Solution:

• Make sure you're properly extracting function calls from the response
• Verify the function call format is correct
• Check your integration credentials in the server deployment

// ✅ Correct - properly extract function calls
let functionCalls = response.candidates?.[0]?.content?.parts
  ?.filter(part => part.functionCall)
  .map(part => part.functionCall!);

if (functionCalls && functionCalls.length > 0) {
  let results = await session.callTools(functionCalls);
  console.log(results);
}

Issue 5: Rate Limiting Errors

Problem: Getting rate limit errors from Google or Metorial.

Solution:

• Implement exponential backoff for retries
• Use Gemini 1.5 Flash for high-volume applications
• Consider upgrading your Metorial plan if hitting limits

async function callWithRetry(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(r => setTimeout(r, Math.pow(2, i) * 1000));
    }
  }
}

Issue 6: TypeScript Type Errors

Problem: Getting TypeScript errors with function calls or tool responses.

Solution:

• Ensure you have the latest versions of all packages
• Use proper type guards when accessing nested properties
• Add null checks for optional fields

// ✅ Safe with type guards
let text = response.candidates?.[0]?.content?.parts?.[0]?.text;

if (text) {
  console.log(text);
}

// Add the non-null assertion only when you're certain
let functionCalls = response.candidates?.[0]?.content?.parts
  ?.filter(part => part.functionCall)
  .map(part => part.functionCall!);

Still Having Issues?

• Check the Metorial documentation for updates
• Review your server deployment configuration
• Verify all integrations have valid credentials
• Look at the Google AI Studio documentation for Gemini-specific issues
• Check that your packages are up to date: npm update @metorial/google metorial @google/genai