Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
381 lines (279 loc) · 9.93 KB

TROUBLESHOOTING.md

File metadata and controls

381 lines (279 loc) · 9.93 KB

Troubleshooting Guide (AI SDK v5)

This guide documents common issues and solutions for the Claude Code AI SDK Provider with v5.

Common Issues

1. Authentication Errors

Problem: Getting authentication errors when trying to use the provider.

Solution:

# Install Claude Code SDK globally
npm install -g @anthropic-ai/claude-code

# Authenticate with your Claude account
claude login

Verification:

# Check if authenticated
npx tsx ../examples/check-cli.ts

2. SDK Not Found

Problem: Error about @anthropic-ai/claude-agent-sdk module not found.

Solution: The SDK is a dependency of this provider and should be installed automatically. If not:

npm install @anthropic-ai/claude-agent-sdk

3. v5 Message Format Errors

Problem: Error about invalid message content format.

Solution: In v5, user messages must have content as an array of parts:

// ❌ Wrong (v4 format)
{ role: 'user', content: 'Hello' }

// ✅ Correct (v5 format)
{ role: 'user', content: [{ type: 'text', text: 'Hello' }] }

4. Streaming API Changes

Problem: Streaming code from v4 doesn't work.

Solution: v5 uses a new streaming pattern with promises:

// ❌ Old v4 pattern
const { textStream } = await streamText({
  model: claudeCode('sonnet'),
  prompt: 'Hello',
});

// ✅ New v5 pattern
const result = streamText({
  model: claudeCode('sonnet'),
  prompt: 'Hello',
});

// Access parts as promises
const text = await result.text;
const usage = await result.usage;

// Or stream chunks
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

5. Token Usage Property Names

Problem: Getting undefined for promptTokens or completionTokens.

Solution: Token properties have been renamed in v5:

// ❌ Old v4 names
console.log(usage.promptTokens);
console.log(usage.completionTokens);

// ✅ New v5 names
console.log(usage.inputTokens);
console.log(usage.outputTokens);
console.log(usage.totalTokens); // New in v5

6. Handling Long-Running Tasks

Problem: Complex queries with Claude Opus 4 may take longer due to extended thinking mode.

Solution: Use AbortSignal with custom timeouts:

import { generateText } from 'ai';
import { claudeCode } from 'ai-sdk-provider-claude-code';

// Create a custom timeout (5 minutes for complex tasks)
const controller = new AbortController();
const timeoutId = setTimeout(() => {
  controller.abort(new Error('Request timeout'));
}, 300000);

try {
  const result = await generateText({
    model: claudeCode('opus'),
    prompt: 'Complex reasoning task...',
    abortSignal: controller.signal,
  });
  clearTimeout(timeoutId);
  console.log(result.text);
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request timed out');
  }
}

Guidelines:

  • Simple queries: Default timeout is sufficient
  • Complex reasoning: 5-10 minutes may be needed
  • Very long tasks: Consider breaking into smaller chunks

7. Object Generation Issues

Problem: Claude returns text instead of valid JSON when using generateObject.

Solutions:

  1. Simplify your schema - Start with fewer fields
  2. Clear prompts - Be explicit: "Generate a user profile with name and age"
  3. Use descriptions - Add .describe() to schema fields
  4. Retry logic - Implement retries for production:
async function generateWithRetry(schema, prompt, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await generateObject({
        model: claudeCode('sonnet'),
        schema,
        prompt,
      });
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, i)));
    }
  }
}

8. Session Management

Problem: Conversations don't maintain context.

Solution: Use message history with v5 format:

import { ModelMessage } from 'ai';

const messages: ModelMessage[] = [
  { role: 'user', content: [{ type: 'text', text: 'My name is Alice' }] },
  { role: 'assistant', content: [{ type: 'text', text: 'Nice to meet you, Alice!' }] },
  { role: 'user', content: [{ type: 'text', text: 'What is my name?' }] },
];

const result = await generateText({
  model: claudeCode('sonnet'),
  messages, // Pass full conversation history
});

Note: While the provider returns session IDs in metadata, the recommended approach is to use message history for conversation continuity.

9. Error Handling

Problem: Need to handle different types of errors appropriately.

Solution: Use the provider's error utilities:

import { isAuthenticationError, getErrorMetadata } from 'ai-sdk-provider-claude-code';

try {
  const result = await generateText({
    model: claudeCode('sonnet'),
    prompt: 'Hello',
  });
} catch (error) {
  if (isAuthenticationError(error)) {
    console.error('Please run: claude login');
  } else if (error.name === 'AbortError') {
    console.error('Request was cancelled or timed out');
  } else {
    // Get additional error details
    const metadata = getErrorMetadata(error);
    console.error('Error details:', metadata);
  }
}

v5-Specific Migration Issues

1. Result Structure Changes

Problem: Code expecting v4 result structure fails.

Solution: Update to v5 result structure:

// ❌ v4 pattern
const { text, usage } = await generateText(...);

// ✅ v5 pattern
const result = await generateText(...);
console.log(result.text);
console.log(result.usage);

2. Stream Event Changes

Problem: Stream events have different names.

Solution: v5 includes a stream-start event:

const result = streamText({
  model: claudeCode('sonnet'),
  prompt: 'Hello',
});

// v5 stream includes: stream-start, text-delta, finish
for await (const chunk of result.fullStream) {
  switch (chunk.type) {
    case 'stream-start':
      console.log('Stream started');
      break;
    case 'text-delta':
      process.stdout.write(chunk.textDelta);
      break;
    case 'finish':
      console.log('Stream finished');
      break;
  }
}

3. Unsupported Settings

Problem: Getting warnings about unsupported settings.

Solution: Some v4 settings are renamed or removed in v5:

// ❌ v4 setting names
{
  maxTokens: 1000;
}

// ✅ v5 setting names
{
  maxOutputTokens: 1000;
}

// Note: Many settings like temperature, topP, etc. are still not supported by Claude Code SDK

Debugging Tips

1. Verify Setup

# Check Claude CLI version
claude --version

# Test authentication
npx tsx ../examples/check-cli.ts

# Run integration tests
npx tsx ../examples/integration-test.ts

2. Enable Debug Logging

// Log provider metadata to debug issues
const result = await generateText({
  model: claudeCode('sonnet'),
  prompt: 'Test',
});

console.log('Metadata:', result.providerMetadata);
// Shows: sessionId, costUsd, durationMs, rawUsage

3. Test Specific Features

# Test streaming
npx tsx ../examples/streaming.ts

# Test object generation
npx tsx ../examples/generate-object-basic.ts

# Test conversations
npx tsx ../examples/conversation-history.ts

# Test long-running tasks
npx tsx ../examples/long-running-tasks.ts

Platform-Specific Issues

Windows

  • Ensure Claude CLI is in your PATH
  • Use PowerShell or Command Prompt (not WSL) for installation

macOS

  • May need to allow CLI in Security & Privacy settings
  • Use Homebrew or direct npm installation

Linux

  • Ensure Node.js ≥ 18 is installed
  • May need to use sudo for global npm installs

Performance Tips

  1. Model Selection

    • Use haiku for fastest, most cost-effective responses
    • Use sonnet for balanced performance
    • Use opus for complex reasoning tasks

  2. Request Optimization

    • Keep prompts concise and clear
    • Use streaming for better UX
    • Implement proper error handling

  3. Resource Management

    • The provider manages concurrent requests automatically
    • Use AbortSignal for cancellable requests
    • Clean up timeouts in finally blocks

Known Limitations

  1. Image Support Requires Streaming Mode: Image inputs are supported via streaming mode with base64/data URLs. See examples/images.ts. Remote HTTP(S) URLs are not supported.
  2. No AI SDK Tool Calling: The AI SDK's function calling interface isn't implemented, but Claude can use tools via MCP servers and built-in CLI tools
  3. Object Generation: Relies on prompt engineering rather than native JSON mode
  4. Model Options: Limited to 'opus', 'sonnet', and 'haiku' models

Getting Help

  1. Check Examples: Review the ../../examples directory for working code
  2. Integration Test: Run npx tsx ../../examples/integration-test.ts to verify setup
  3. GitHub Issues: Report bugs at https://github.com/ben-vargas/ai-sdk-provider-claude-code/issues
  4. Documentation: See the README.md and GUIDE.md for detailed API documentation

Common Error Messages

Error Cause Solution
"Claude Code executable not found" CLI not installed Run npm install -g @anthropic-ai/claude-code
"Authentication required" Not logged in Run claude login
"No object generated" Invalid JSON response Simplify schema, improve prompt
"Request timeout" Task took too long Increase timeout with AbortSignal
"Session not found" Invalid session ID Use message history instead
"Invalid message content" v4 message format Update to v5 array format
"promptTokens is undefined" v4 property names Use inputTokens/outputTokens