Common Issues
Solutions to frequently encountered problems
Common Solutions
No Ads Showing
No Ads Showing
Check API Key
Verify
EARNLAYER_API_KEY is set in .env.local:cat .env.local | grep EARNLAYER
Should show:
EARNLAYER_API_KEY=el_...
EARNLAYER_MCP_URL=https://mcp.earnlayerai.com/mcp
Restart Dev Server
Environment variables require a full restart:
# Stop server (Ctrl+C)
npm run dev
Check Browser Console
Look for errors in browser DevTools console:
[earnlayer SDK] Failed to initialize conversation: ...
Verify Proxy Endpoint
Test the proxy:
curl -X POST http://localhost:3000/api/earnlayer/initialize
Should return:
{ "conversation_id": "conv_..." }AI Not Calling MCP Tool
AI Not Calling MCP Tool
Use Specific Questions
"What VPN should I use?"
"Best project management tools?"
Avoid: "Hello"
Avoid: "How are you?"
Check System Instructions
Verify
SYSTEM_INSTRUCTIONS is included in your prompts.Verify MCP Configuration
Check headers are correct:
headers: {
'x-api-key': EARNLAYER_API_KEY,
'x-conversation-id': conversationId
}
Display Ads Not Showing
Display Ads Not Showing
Check Conversation ID
const { conversationId } = useEarnLayerClient();
console.log('Conversation ID:', conversationId);
Should not be
null.Check Network Tab
DevTools → Network → Filter by
earnlayer:Look for
/api/earnlayer/displayad/... requests. Status should be 200 OK
.Try Manual Refetch
const { refetch } = useDisplayAd({ });
// In button or useEffect
refetch();
Not Seeing Enough Ads / Limited Ad Inventory
Not Seeing Enough Ads / Limited Ad Inventory
Cause
You're in production mode without partnerships configured, or demo mode is disabled during testing.
Solution
For testing:
Enable demo mode to see all demo ads
initializeConversation({ demoMode: true })
Common Error Messages
Common Error Messages
"Invalid earnlayer API key"
Cause: Invalid or expired API key
Solution: Verify
Get new key EARNLAYER_API_KEY starts with el_"API rate limit exceeded"
Cause: Too many requests
Solution: Wait 1 minute, or contact support for higher limits
"Cannot fetch display ad: conversationId not available"
Cause: Trying to fetch ads before
initializeConversation()Solution: Call
initializeConversation() on mount"Failed to initialize conversation"
Cause: Network issue or authentication problem
Solution: Check API key, network connection, console for details
Module Not Found Errors
Module Not Found Errors
"@earnlayer/sdk not found"
npm install @earnlayer/sdk
"openai not found"
npm install openai
"@google/genai not found"
npm install @google/genai @modelcontextprotocol/sdk