Troubleshooting

Common issues and how to fix them.

Flowise Integration Issues

"DriftOS node not appearing in Flowise"

Solution: Restart Flowise server.

# Stop Flowise
# Restart Flowise
npm start

The DriftOS node should appear in the Memory category after restart.

"Connection refused" or "401 Unauthorized"

Symptoms:

• API calls fail with 401 or connection errors
• Logs show "Unauthorized" or "Connection refused"

Solutions:

1. Check API key

   • Verify key is correct in Flowise credentials
   • Get a fresh key from driftos.dev

2. Check endpoint

   • If Use Hosted API is ON, no custom endpoint needed
   • If Use Hosted API is OFF, verify custom endpoint is reachable

3. Check network

   • Ensure Flowise can reach api.driftos.dev
   • Check firewall settings

"Falling back to database messages"

What it means:

DriftOS encountered an error and Flowise fell back to standard memory.

Logs:

❌ DriftOS routing error: [error message]
   Falling back to standard memory

Why this happens:

• DriftOS API is down
• Network connectivity issue
• Invalid API key
• Rate limit exceeded

What to do:

1. Check the error message in logs for details
2. Verify API key is valid
3. Check API status at status.driftos.dev
4. Wait and retry if it's a temporary outage

Good news: Your chatflow continues working normally. No user-facing errors.

"Could not determine a valid conversation ID"

Symptoms:

• DriftOS can't find a conversation ID
• Routing fails immediately

Solutions:

1. If Use Flowise Chat ID is ON:

   • This should work automatically
   • Ensure you're using a supported Flowise version
   • Try turning it OFF and providing a custom Chat ID

2. If Use Flowise Chat ID is OFF:

   • You must provide a custom Chat ID in the node config
   • Example: my-custom-session-id

Routing decisions seem wrong

Symptoms:

• DriftOS creates unexpected branches
• Messages go to wrong topics

Debug steps:

1. Check the logs - DriftOS explains its reasoning:

   🎯 Routing Decision:
      Reason: New semantic context detected: pet adoption inquiry

2. Adjust configuration:

   • Increase Max Context Messages if branches are too fragmented
   • Add a System Prompt to guide routing behavior

3. Try different routing engine:

   • Switch between driftos-core and driftos-embed
   • Core is more accurate, Embed is more deterministic

4. Check for edge cases:

   • Sarcasm (Core handles better than Embed)
   • Negation ("I don't want X" - Core handles better)
   • Synonyms (Core handles better)

Learn more about routing engines →

SDK Issues

"Invalid API key"

Error:

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED",
    "statusCode": 401
  }
}

Solution:

1. Check your API key in code
2. Verify it starts with dft_live_
3. Ensure the key hasn't been revoked
4. Try using the x-api-key header instead of Authorization: Bearer
5. Get a fresh key from driftos.dev

"Request timeout"

Error:

Error: Request timeout after 30000ms

Solutions:

1. Increase timeout:

   const drift = createDriftClient(baseUrl, apiKey, {
     timeout: 60000 // 60 seconds
   });

2. Check network connection

3. Verify API status at status.driftos.dev

"Module not found: @driftos/client"

Error:

Error: Cannot find module '@driftos/client'

Solution:

npm install @driftos/client

Ensure package is in your package.json.

API Issues

Rate Limits

Error:

{
  "error": "Rate limit exceeded. Retry after 60 seconds."
}

Solutions:

1. Wait 60 seconds and retry
2. Implement backoff in your code
3. Contact support for higher limits

500 Internal Server Error

Error:

{
  "error": "Internal server error"
}

Solutions:

1. Retry the request - might be temporary
2. Check API status at status.driftos.dev
3. Report persistent errors on Discord

Common Questions

"Too many branches being created"

Issue: DriftOS creates more branches than expected.

Why:

• Embed: Cannot ROUTE to old topics—creates new branches instead
• Core: Might be detecting subtle topic shifts you didn't expect

Solutions:

1. Switch to Core for smarter topic detection (if using Embed)
2. Review routing logs to understand why branches are created
3. Adjust system prompt to guide routing behavior
4. Accept more branches - they're pruned from context anyway

"Routing is too slow"

Issue: Routing latency is high.

Solutions:

1. Switch to Embed for sub-50ms routing (if using Core)
2. Check network latency to api.driftos.dev
3. Self-host DriftOS for lower latency

Learn about choosing a routing engine →

"Context is too short"

Issue: Not enough messages in context.

Solutions:

1. Increase Max Context Messages in Flowise node or SDK:

   const { messages } = await drift.buildPrompt(branchId, {
     maxMessages: 20 // Increase from default 10
   });

2. Check branch message count in logs:

   🌳 Branch: dog-adoption (3 messages)

   If the branch only has 3 messages, that's all you'll get.

Still Stuck?

Get help:

• GitHub: driftos/driftos-client/issues
• Discord: driftos.dev/discord
• Docs: driftos.dev/docs