Troubleshooting

Solutions to common issues you might encounter when using ArcanFlows.

AI Agent Issues

Agent not responding

Symptoms:

• Agent doesn't reply to messages
• Timeout errors
• Empty responses

Solutions:

1. Check API key validity

   • Go to Settings > AI Providers
   • Verify your API key is correct
   • Test the connection

2. Check model availability

   • Some models may be deprecated or unavailable
   • Try switching to a different model

3. Review rate limits

   • You may have exceeded provider rate limits
   • Wait a few minutes and try again

4. Check system prompt

   • A very long or complex prompt may cause issues
   • Try simplifying the prompt

Agent giving incorrect answers

Solutions:

1. Improve system prompt

   • Be more specific about the agent's role
   • Add examples of correct responses
   • Define what the agent should NOT do

2. Update knowledge base

   • Ensure documents are up to date
   • Check chunking settings
   • Verify document formatting

3. Adjust model parameters

   • Lower temperature for more consistent answers
   • Increase context length if needed

Knowledge base not being used

Symptoms:

• Agent ignores uploaded documents
• Answers don't reference your content

Solutions:

1. Wait for processing

   • Document processing takes a few minutes
   • Check the processing status in the knowledge base

2. Check document format

   • Ensure documents are readable (not scanned images)
   • PDF text should be selectable, not images

3. Review chunking settings

   • Chunks may be too small or too large
   • Try adjusting chunk size and overlap

Workflow Issues

Workflow not triggering

Symptoms:

• Webhook not receiving data
• Schedule not running
• Form not triggering workflow

Solutions:

1. Check workflow status

   • Ensure workflow is published (not draft)
   • Verify it's not paused

2. Verify trigger configuration

   • For webhooks: check the URL is correct
   • For schedules: verify cron expression
   • For forms: ensure form is connected

3. Check logs

   • Go to Activity > Workflow Logs
   • Look for error messages

Workflow execution failing

Solutions:

1. Check node configuration

   • Review each node's settings
   • Verify all required fields are filled

2. Inspect input data

   • Use the debugger to see actual input
   • Verify data types match expectations

3. Review error messages

   • Check the execution log for details
   • Look for specific error codes

HTTP Request node failures

Symptoms:

• External API calls failing
• Timeout errors
• Connection refused

Solutions:

1. Verify URL

   • Check for typos in the URL
   • Ensure HTTPS is used if required

2. Check authentication

   • Verify API keys/tokens are correct
   • Check header format

3. Review firewall rules

   • Some APIs block certain IP ranges
   • Contact support if whitelisting is needed

4. Increase timeout

   • Slow APIs may need longer timeout
   • Adjust in node settings

Form Issues

Form not loading

Solutions:

1. Check form status

   • Ensure form is published
   • Verify the URL is correct

2. Clear browser cache

   • Hard refresh (Cmd/Ctrl + Shift + R)
   • Try incognito/private mode

3. Check for JavaScript errors

   • Open browser developer tools
   • Look for errors in console

Form submissions not working

Solutions:

1. Check validation

   • Ensure all required fields are filled
   • Verify field formats are correct

2. Check integration

   • Verify workflow is connected
   • Check agent connection if applicable

3. Review logs

   • Check form submission logs
   • Look for error messages

Conditional logic not working

Solutions:

1. Verify conditions

   • Check field names match exactly
   • Verify comparison operators

2. Test with simple conditions

   • Start with basic if/then
   • Build complexity gradually

Integration Issues

API key not working

Solutions:

1. Verify key format

   • Check for extra spaces
   • Ensure full key is copied

2. Check permissions

   • Verify key has required scopes
   • Some keys may be read-only

3. Test with provider directly

   • Try the key in provider's dashboard
   • Verify account is active

Notification not sending

Solutions:

1. Check channel configuration

   • Verify API keys/tokens
   • Test connection in settings

2. Check recipient

   • Verify email/phone/channel is valid
   • Check for formatting issues

3. Review rate limits

   • Provider may rate limit
   • Check provider dashboard

Webhook not receiving data

Solutions:

1. Verify URL

   • Copy URL directly from ArcanFlows
   • Ensure no extra characters

2. Check HTTP method

   • Webhooks expect POST by default
   • Verify sender is using correct method

3. Inspect payload

   • Use webhook.site to debug
   • Verify JSON format

Performance Issues

Slow response times

Solutions:

1. Optimize prompts

   • Shorter prompts process faster
   • Remove unnecessary instructions

2. Choose faster models

   • GPT-3.5 is faster than GPT-4
   • Claude Haiku is fastest for Anthropic

3. Reduce context

   • Limit conversation history
   • Optimize knowledge base size

High costs

Solutions:

1. Use smaller models

   • GPT-3.5 is cheaper than GPT-4
   • Start with smaller models

2. Limit token usage

   • Set max tokens appropriately
   • Optimize prompts for brevity

3. Cache responses

   • Enable response caching
   • Use for repeated queries

Getting More Help

If these solutions don't resolve your issue:

1. Check the logs - Detailed error messages are in Activity
2. Search documentation - Use the search bar above
3. Contact support - Email support@arcanflows.io
4. Community - Ask in Discord or GitHub