Troubleshooting

This guide covers common issues and their solutions for each major feature of the Girard AI platform.

Table of Contents

1. Authentication & Authorization
2. Workflows
3. AI Studio
4. Voice Agents
5. Chat Agents
6. Integrations & Connections
7. Billing & Subscriptions
8. API Issues
9. Performance Issues

Authentication & Authorization

Can't Sign In

Symptoms: Login fails, redirects back to sign-in page

Solutions:

1. Clear browser cookies and cache

   Settings > Privacy > Clear browsing data > Cookies and cached images
   

2. Check if account exists

   • Try the "Forgot Password" flow to verify email is registered
   • Check spam folder for verification emails

3. SSO issues

   • Ensure your organization has SSO enabled
   • Contact your IT admin to verify your account is provisioned

4. Session expired

   • Sign out completely and sign back in
   • Try incognito/private browsing mode

"Unauthorized" Errors in Dashboard

Symptoms: Pages show "Unauthorized" or redirect unexpectedly

Solutions:

1. Refresh the page - Session token may have expired
2. Check organization membership - Verify you're a member of the organization
3. Verify role permissions - Some features require Admin or Owner role
4. Clear local storage:

   // In browser console
   localStorage.clear();
   location.reload();
   

API Key Not Working

Symptoms: API returns INVALID_API_KEY or MISSING_API_KEY

Solutions:

1. Check key format: Must start with gai_sk_ or gai_pk_
2. Verify key is active: Check API Keys page in dashboard
3. Check Authorization header format:

   # Correct
   Authorization: Bearer gai_sk_abc123...
   
   # Incorrect
   Authorization: gai_sk_abc123...
   Authorization: Bearer "gai_sk_abc123..."
   

4. Regenerate the key if compromised or lost

Workflows

Workflow Won't Execute

Symptoms: "Execute" button doesn't work, execution fails immediately

Solutions:

1. Check workflow is active

   • Toggle the "Active" switch in workflow settings
   • Inactive workflows cannot be executed

2. Verify all required fields

   • Each step must have valid configuration
   • AI steps need a prompt
   • HTTP steps need a valid URL

3. Check usage limits

   • View Usage page to see if you've hit monthly limits
   • Upgrade plan or wait for reset

4. Validate input data

   • Input must match expected schema
   • Check for required fields in trigger configuration

Workflow Execution Stuck

Symptoms: Run shows "Running" for extended period, never completes

Solutions:

1. Check AI provider status

   • Anthropic Status
   • OpenAI Status

2. Review step timeout settings

   • Default timeout is 30 seconds
   • Increase for complex AI operations

3. Check for infinite loops

   • Review conditional logic
   • Ensure loop exit conditions are reachable

4. Cancel and retry

   • Use the "Cancel" button on the run detail page
   • Create a new execution

Workflow Outputs Not as Expected

Symptoms: AI responses are wrong, data isn't passing between steps

Solutions:

1. Check variable references

   • Use {{step_name.output}} format
   • Verify step names match exactly (case-sensitive)

2. Debug with logging

   • Add a "Log" step between problematic steps
   • Check run details for intermediate values

3. Improve AI prompts

   • Be more specific about output format
   • Include examples in the prompt
   • Use JSON mode for structured output

4. Check data types

   • Ensure numbers aren't being treated as strings
   • Parse JSON responses before using

AI Studio

Generation Fails

Symptoms: "Generation failed" error, no output produced

Solutions:

1. Check API key configuration

   • Verify AI provider keys in Settings > API Keys
   • Different providers for different media types

2. Review prompt content

   • Avoid prohibited content
   • Keep prompts under token limits
   • Remove special characters that might cause issues

3. Check file upload

   • Image inputs must be under 10MB
   • Supported formats: PNG, JPG, WEBP

4. Try a different model

   • Some models have different capabilities
   • Switch between providers if one is having issues

Poor Image Quality

Symptoms: Images are blurry, wrong style, or don't match prompt

Solutions:

1. Use HD mode

   • Enable "HD Quality" in generation settings
   • Uses DALL-E 3 HD or equivalent

2. Improve prompt specificity

   # Bad
   "A dog"
   
   # Good
   "A golden retriever puppy playing in autumn leaves,
   professional photography, soft natural lighting,
   shallow depth of field, 4K resolution"
   

3. Use negative prompts (if supported)

   • Specify what to avoid: "no text, no watermarks"

4. Try upscaling

   • Generate at standard quality
   • Use the "Upscale" feature for higher resolution

Audio Generation Issues

Symptoms: TTS sounds robotic, wrong voice, audio clipping

Solutions:

1. Select appropriate voice

   • Preview voices before generating
   • Match voice to content type

2. Break long text into segments

   • Maximum recommended: 4096 characters
   • Use SSML for precise control

3. Adjust speed and pitch

   • Use the adjustment sliders
   • Default is often best for clarity

Voice Agents

Calls Not Connecting

Symptoms: Outbound calls fail, inbound calls don't reach agent

Solutions:

1. Verify Twilio configuration

   • Check TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN
   • Verify phone number is active in Twilio console

2. Check webhook URL

   • Must be publicly accessible (not localhost)
   • Verify SSL certificate is valid
   • URL: https://yourdomain.com/api/voice/webhook

3. Phone number format

   • Use E.164 format: +1234567890
   • Include country code

4. Check Twilio account balance

   • Outbound calls require sufficient balance

Poor Call Quality

Symptoms: Audio choppy, delays, echo

Solutions:

1. Network issues

   • Check internet connection stability
   • Minimum recommended: 1 Mbps upload

2. Reduce AI response complexity

   • Shorter responses = faster processing
   • Use streaming where available

3. Check Twilio region

   • Use closest Twilio region to your users

Agent Not Responding Correctly

Symptoms: Wrong responses, doesn't understand callers

Solutions:

1. Improve system prompt

   • Be specific about agent's role
   • Include example conversations

2. Adjust speech recognition settings

   • Check language setting matches callers
   • Consider accent variations

3. Review call flow logic

   • Test each branch of the IVR
   • Verify conditions are correct

Chat Agents

Widget Not Loading

Symptoms: Chat bubble doesn't appear, widget shows blank

Solutions:

1. Check embed code

   <!-- Verify script is included -->
   <script src="https://widget.girardai.com/chat.js" data-agent-id="your-agent-id"></script>
   

2. Check allowed domains

   • Agent must allow your domain in settings
   • Include both www and non-www versions

3. Check browser console

   • Look for JavaScript errors
   • Check for Content Security Policy blocks

4. CORS issues

   • Widget domain must be in allowed origins
   • Check for mixed content (HTTP/HTTPS)

Agent Not Responding

Symptoms: Messages sent but no response appears

Solutions:

1. Check agent is published

   • Toggle "Published" in agent settings

2. Verify AI configuration

   • Agent needs valid AI model selected
   • Check system prompt isn't empty

3. Check rate limits

   • Free tier: 100 messages/day
   • Upgrade for higher limits

4. Review conversation context

   • Clear conversation and start fresh
   • Long conversations may hit token limits

Styling Issues

Symptoms: Widget looks wrong, conflicts with site styles

Solutions:

1. Use custom CSS

   .girardai-widget {
     --primary-color: #your-color;
     --font-family: 'Your Font';
   }
   

2. Check z-index conflicts

   • Widget uses z-index: 9999
   • Adjust if other elements overlap

3. Responsive issues

   • Widget is responsive by default
   • Check viewport meta tag

Integrations & Connections

OAuth Connection Fails

Symptoms: "Connection failed" after OAuth redirect

Solutions:

1. Check callback URL

   • Must match exactly in provider settings
   • Format: https://app.girardai.com/api/integrations/callback

2. Verify client credentials

   • Check Client ID and Secret
   • Regenerate if expired

3. Check required scopes

   • Some integrations need specific permissions
   • Review integration documentation

4. Try reconnecting

   • Delete existing connection
   • Create new connection

Webhook Not Triggering

Symptoms: External events don't trigger workflows

Solutions:

1. Verify webhook URL

   • Copy from Workflow > Triggers > Webhook
   • URL is unique per workflow

2. Check webhook payload

   • Must be valid JSON
   • Check Content-Type header

3. Review webhook logs

   • Go to Workflow > Triggers > Webhook Logs
   • Check for delivery failures

4. Test with curl

   curl -X POST https://api.girardai.com/webhooks/wh_xxx \
     -H "Content-Type: application/json" \
     -d '{"test": true}'
   

API Integration Errors

Symptoms: Integration actions fail in workflows

Solutions:

1. Check connection health

   • Go to Connections page
   • Look for "Needs Reconnection" status

2. Verify API permissions

   • Some operations need elevated access
   • Re-authorize with broader scopes

3. Check rate limits

   • External APIs have their own limits
   • Add delays between requests

Billing & Subscriptions

Payment Failed

Symptoms: Subscription inactive, payment error message

Solutions:

1. Update payment method

   • Go to Billing > Payment Methods
   • Add new card or update existing

2. Check card details

   • Verify expiration date
   • Ensure sufficient funds

3. Contact your bank

   • Some banks block international transactions
   • Pre-authorize the charge

4. Try alternative payment

   • Different card
   • PayPal (if available)

Usage Not Updating

Symptoms: Dashboard shows old usage numbers

Solutions:

1. Wait for sync

   • Usage updates every few minutes
   • Check back in 5 minutes

2. Refresh the page

   • Usage is cached client-side
   • Hard refresh: Ctrl+Shift+R

3. Check billing period

   • Usage resets monthly
   • Verify you're viewing current period

Can't Upgrade/Downgrade

Symptoms: Plan change fails or isn't reflected

Solutions:

1. Clear outstanding invoices

   • Pay any failed invoices first
   • Check Billing > Invoice History

2. Contact support

   • Enterprise plans require manual changes
   • Email: billing@girardai.com

API Issues

Slow API Responses

Symptoms: API calls take >5 seconds

Solutions:

1. Check request size

   • Large payloads take longer
   • Paginate large result sets

2. Use appropriate endpoints

   • Use list endpoints with filters
   • Don't fetch all data if you need one item

3. Enable caching

   • Cache responses client-side
   • Use ETags for conditional requests

4. Check your connection

   • Test from different network
   • Use closest region

Inconsistent Results

Symptoms: Same request returns different data

Solutions:

1. Check for concurrent modifications

   • Another process may be updating data
   • Use optimistic locking

2. Verify pagination

   • Results may shift between pages
   • Use cursor-based pagination

3. Check timestamp filters

   • Time-based queries may vary
   • Use explicit timestamps

Performance Issues

Dashboard Loading Slowly

Symptoms: Pages take >3 seconds to load

Solutions:

1. Check your connection

   • Speed test: fast.com
   • Try wired connection

2. Clear browser cache

   • Cached assets may be corrupted
   • Clear and reload

3. Disable browser extensions

   • Ad blockers can interfere
   • Try incognito mode

4. Check for large data

   • Many workflows/projects slow down lists
   • Use search and filters

High Memory Usage

Symptoms: Browser tab uses excessive memory

Solutions:

1. Close unused tabs

   • Real-time features use WebSockets
   • Each tab maintains connections

2. Refresh periodically

   • Long sessions accumulate memory
   • Refresh every few hours

3. Use desktop app (coming soon)

   • Native app is more efficient

Getting Help

If these solutions don't resolve your issue:

1. Check Status Page: status.girardai.com
2. Search Documentation: docs.girardai.com
3. Community Forum: community.girardai.com
4. Contact Support: support@girardai.com

When contacting support, include:

• Your organization ID
• Request ID (from error messages)
• Steps to reproduce
• Screenshots or error messages
• Browser/OS version

Last updated: January 22, 2026