Skip to main content
←→

Debugging Guide

When things don't work as expected, this guide helps you diagnose and fix common issues.

Quick Diagnosis​

Is your service running?
Check terminal for errors, verify "🟢 Online" in dashboard
↓
Are functions registered?
Check dashboard → Services → Your functions should appear
↓
Is the right function called?
Watch CLI stream or Playground function trace
↓
Does the function return correct data?
Check function_result in stream or add console.log

Common Issues​

1. Service Won't Connect​

Symptoms: Service doesn't show as online, connection errors in terminal.

Check:

# Verify environment variables are set
echo $DAEMO_AGENT_API_KEY

# Check for typos in your .env file
cat .env | grep DAEMO

Common causes:

  • Missing or invalid DAEMO_AGENT_API_KEY
  • Network/firewall blocking connection
  • Wrong gateway URL

Fix:

# Ensure .env is loaded
npm install dotenv

# In your entry point
import 'dotenv/config';

2. Functions Not Appearing in Dashboard​

Symptoms: Service is online but functions list is empty.

Check:

  • Are decorators imported?
  • Is the service instance registered?
// ❌ Missing import
class MyFunctions {
  @DaemoFunction({ description: "..." }) // Error: DaemoFunction is not defined
  async myFunc() {}
}

// ✅ Correct
import { DaemoFunction } from 'daemo-engine';

class MyFunctions {
  @DaemoFunction({ description: "..." })
  async myFunc() {}
}
// ❌ Forgot to register
const builder = new DaemoBuilder().withServiceName("my_service");
builder.build(); // Functions never registered!

// ✅ Correct
const myFuncs = new MyFunctions();
builder.registerService(myFuncs); // Register the instance
builder.build();

3. Wrong Function Called​

Symptoms: AI calls a different function than expected.

Diagnosis: Use CLI testing and watch the function_call events.

Fix: Improve your function descriptions:

// ❌ Too vague - AI can't distinguish
@DaemoFunction({ description: "Search contacts" })
async searchByEmail() {}

@DaemoFunction({ description: "Search contacts" })
async searchByCompany() {}

// ✅ Specific - AI knows which to use
@DaemoFunction({ 
  description: "Search contacts by email address. Supports partial matching (e.g., 'john' matches 'john@example.com')." 
})
async searchByEmail() {}

@DaemoFunction({ 
  description: "Search contacts by company name. Returns all contacts who work at the specified company." 
})
async searchByCompany() {}
Tip

Rule of thumb: Your description should answer "When should the AI call this function?"

4. Function Returns Error​

Symptoms: function_result shows an error message.

Diagnosis: Check your service logs:

# Your service terminal will show the error
[ERROR] Database error: connection refused

Common causes:

  • Database not running
  • Missing environment variables
  • Invalid input data

Fix: Add error handling with clear messages:

@DaemoFunction({ description: "Get contact by ID" })
async getContact(input: { id: string }) {
  try {
    const { data, error } = await supabase
      .from('contacts')
      .select('*')
      .eq('id', input.id)
      .single();
    
    if (error) throw error;
    if (!data) throw new Error(`Contact not found: ${input.id}`);
    
    return data;
  } catch (err) {
    // Clear error message for the AI to relay
    throw new Error(`Failed to get contact: ${err.message}`);
  }
}

5. "No final_response found"​

Symptoms: CLI script shows no final response.

Possible causes:

  • Request timed out
  • Service crashed mid-request
  • Stream interrupted

Diagnosis:

# Check if service is still running
# Look for errors in service terminal

# Try a simpler query
./ask.sh "Hello"

6. Authentication Errors​

Symptoms: 401 or 403 errors.

Fix:

# Regenerate your auth token
# Go to app.daemo.ai → Agent → Settings → Regenerate Key

# Update .auth_token
echo "new-token-here" > .auth_token

Debugging Tools​

1. Console Logging​

Add logs in your functions:

@DaemoFunction({ description: "..." })
async myFunction(input: { query: string }) {
  console.log('[myFunction] Called with:', JSON.stringify(input));
  
  const result = await doSomething(input);
  console.log('[myFunction] Returning:', JSON.stringify(result));
  
  return result;
}

2. CLI Stream Analysis​

The CLI shows the full event stream:

./ask.sh "test query" 2>&1 | grep function_call

3. Dashboard Logs​

Check Logs in the Daemo dashboard for:

  • Timestamps
  • Function inputs/outputs
  • Execution duration
  • Errors

Performance Issues​

Slow Responses​

Diagnosis: Check which function is slow:

@DaemoFunction({ description: "..." })
async slowFunction(input: any) {
  const start = Date.now();
  
  const result = await doWork();
  
  console.log(`[slowFunction] Took ${Date.now() - start}ms`);
  return result;
}

Common fixes:

  • Add database indexes
  • Reduce data returned (use .limit())
  • Cache frequently-accessed data
  • Add timeouts to external API calls

Timeouts​

If functions take too long, they may timeout:

// Add timeout to external calls
const response = await axios.get(url, { timeout: 10000 }); // 10 seconds

Getting Help​

1. Check the Logs​

Always start with logs:

  • Service terminal output
  • Dashboard logs
  • Browser console (for Playground issues)

2. Reproduce with CLI​

Use CLI testing to get the exact error:

./ask.sh "the failing query" 2>&1 | tee debug.log

3. Simplify​

Reduce to the minimum failing case:

  • Test with a simple function
  • Try with minimal input
  • Remove complexity until it works

Debugging Checklist​

CLI Testing

Debug with full stream visibility

Defining Tools

Write better function descriptions

Dashboard

View logs and function details