Documentation Index
Fetch the complete documentation index at: https://mintlify.com/tambo-ai/tambo/llms.txt
Use this file to discover all available pages before exploring further.
This guide covers common issues you may encounter when working with Tambo and how to resolve them.
Installation Issues
npm Install Fails
Problem: npm install fails with dependency resolution errors.
Solution:
# Clear npm cache
npm cache clean --force
# Remove node_modules and lock file
rm -rf node_modules package-lock.json
# Reinstall
npm install
node --version # Should show v22.x.x or higher
# Using nvm
nvm install 22
nvm use 22
# Using mise (recommended)
mise install
Package Manager Issues
Problem: Wrong package manager detected by CLI.
Solution: The CLI auto-detects your package manager. Override with:
# Force npm
tambo add message --package-manager=npm
# Force pnpm
tambo add message --package-manager=pnpm
# Force yarn
tambo add message --package-manager=yarn
Authentication Issues
API Key Not Found
Problem: “API key not found” error when running app.
Solution:
- Check environment variable is set:
# Next.js
echo $NEXT_PUBLIC_TAMBO_API_KEY
# Vite
echo $VITE_TAMBO_API_KEY
- Verify .env file exists and has correct prefix:
# Next.js - .env.local
NEXT_PUBLIC_TAMBO_API_KEY=sk_...
# Vite - .env
VITE_TAMBO_API_KEY=sk_...
- Restart dev server after changing .env:
Invalid API Key
Problem: “Invalid API key” or 401 errors.
Solution:
- Generate new key at Tambo Cloud
- Verify key is correctly copied (no extra spaces)
- Check key format:
sk_live_... or sk_test_...
Authentication Required for CLI
Problem: CLI commands require authentication.
Solution:
# Login with browser
tambo auth login
# Login without browser (for SSH/remote)
tambo auth login --no-browser
# Copy URL and open in local browser
Streaming Issues
No Streaming Updates
Problem: Components don’t update during AI response.
Solution:
- Verify streamable hint is enabled:
const components: TamboComponent[] = [
{
name: "MyComponent",
streamable: true, // Add this
component: MyComponent,
propsSchema: z.object({...}),
},
];
- Check component uses streaming status:
const { propStatus } = useTamboComponentState("myKey", initialState);
if (propStatus.isPending) {
return <div>Loading...</div>;
}
Streaming Stops Mid-Response
Problem: Streaming cuts off before completion.
Solution:
- Check network connection
- Verify API endpoint is accessible
- Check for rate limiting (429 errors)
- Increase timeout if using custom fetch:
const client = new TamboClient({
apiKey: "...",
timeout: 60000, // 60 seconds
});
Component Issues
Component Not Rendering
Problem: AI-generated components don’t appear.
Solution:
- Verify component is registered:
const components: TamboComponent[] = [
{
name: "MyComponent", // Must match exactly
component: MyComponent,
propsSchema: z.object({...}),
},
];
<TamboProvider components={components}>
{/* app */}
</TamboProvider>
- Check component name matches (case-sensitive):
// Component registration
name: "GraphComponent"
// AI will call
tool: "GraphComponent"
- Verify props schema is valid:
// Invalid - z.record not supported
propsSchema: z.record(z.string())
// Valid - use z.object
propsSchema: z.object({
data: z.array(z.object({ name: z.string(), value: z.number() })),
})
Component Validation Errors
Problem: “Component name too long” or validation errors.
Solution:
- Keep component names under 64 characters
- Avoid spaces in names:
// Invalid
name: "My Graph Component"
// Valid
name: "MyGraphComponent"
- No special characters except underscore:
// Invalid
name: "Graph-Component"
// Valid
name: "Graph_Component"
Database Issues (Self-Hosted)
Connection Failed
Problem: Cannot connect to database.
Supabase Solution:
# Check Supabase is running
npx supabase status
# Restart if needed
npx supabase stop
npx supabase start
# Verify DATABASE_URL in .env
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
# Check container is running
docker compose --env-file docker.env ps postgres
# View logs
docker compose --env-file docker.env logs postgres
# Restart if needed
docker compose --env-file docker.env restart postgres
# Verify DATABASE_URL uses correct port (5433, not 5432)
DATABASE_URL=postgresql://postgres:password@localhost:5433/tambo
Migration Errors
Problem: Database migrations fail.
Solution:
# Check migration status
npm run db:check -w packages/db
# Reset database (WARNING: deletes all data)
npx supabase db reset
# Re-run migrations
npm run db:migrate -w packages/db
Port Conflicts
Problem: “Port already in use” errors.
Solution:
- Check what’s using the port:
# macOS/Linux
lsof -ti:8260 | xargs kill -9
lsof -ti:8261 | xargs kill -9
# Windows
netstat -ano | findstr :8260
taskkill /PID <PID> /F
- Change ports in configuration:
# docker.env
WEB_PORT=8270
API_PORT=8271
Build Issues
TypeScript Errors
Problem: Type errors during build.
Solution:
# Check types
npm run check-types
# Update TypeScript
npm install typescript@latest -D
# Clear TypeScript cache
rm -rf node_modules/.cache
Tailwind CSS Not Working
Problem: Tailwind styles not applied.
Solution:
- Verify Tailwind config includes component paths:
// tailwind.config.js
module.exports = {
content: [
"./src/**/*.{js,ts,jsx,tsx}",
"./components/**/*.{js,ts,jsx,tsx}",
"./app/**/*.{js,ts,jsx,tsx}",
],
};
- Import Tailwind in your CSS:
/* globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
- For CLI components, run setup:
tambo init
# Select "Yes" for Tailwind setup
MCP Issues
MCP Server Connection Failed
Problem: Cannot connect to MCP server.
Solution:
- Verify server is running:
curl http://localhost:8261/mcp
- Check transport type matches:
import { MCPTransport } from "@tambo-ai/react/mcp";
const mcpServers = [
{
name: "my-server",
url: "http://localhost:8261/mcp",
transport: MCPTransport.HTTP, // Not SSE
},
];
- Verify MCP token if required:
<TamboProvider
mcpServers={mcpServers}
mcpAccessToken={token}
>
- Check server connection status:
const { servers } = useTamboMCPServers();
console.log(servers); // Check connection state
- Verify tools are exposed by server:
# Test MCP endpoint
curl http://localhost:8261/mcp/tools
Slow Response Times
Problem: AI responses are slow.
Solution:
-
Use faster models:
- GPT-3.5 Turbo instead of GPT-4
- Claude Haiku instead of Opus
- Cerebras for ultra-fast inference
-
Reduce context size:
const { messages } = useTambo();
const recentMessages = messages.slice(-10); // Last 10 messages
- Enable streaming:
High Memory Usage
Problem: Application uses too much memory.
Solution:
- Limit message history:
const MAX_MESSAGES = 50;
const limitedMessages = messages.slice(-MAX_MESSAGES);
- Clean up old threads:
const { deleteThread } = useTambo();
// Delete old threads
await deleteThread(oldThreadId);
- Use React.memo for expensive components:
export const MyComponent = React.memo(({ data }) => {
// Component implementation
});
Getting More Help
If these solutions don’t resolve your issue:
- Search GitHub Issues: github.com/tambo-ai/tambo/issues
- Ask on Discord: discord.gg/dJNvPEHth6
- Check Documentation: docs.tambo.co
- Open New Issue: Provide:
- Tambo version
- Node.js version
- Steps to reproduce
- Error messages
- Relevant code snippets