Workflows
Troubleshooting

Troubleshooting Guide

Common issues and solutions for the Zara Automated Workflow System.

🚨 Common Issues

Workflow Stuck or Hanging

Symptoms

  • Workflow shows "In Progress" for extended periods
  • No status updates in the dashboard
  • Linear issues not progressing

Diagnosis Steps

  1. Check Linear Issue Status

    • Verify the issue exists in Linear
    • Check if the issue has been moved to a different state
    • Look for any error messages in the issue description

  2. Check GitHub Actions

    • Go to your repository's Actions tab
    • Look for any failed or stuck workflows
    • Check if the workflow is waiting for manual approval

  3. Verify Webhook Delivery

    • Check webhook delivery logs in Linear
    • Verify webhook endpoint is accessible
    • Check for webhook signature validation errors

Solutions

# Check webhook endpoint status
curl -X GET https://your-domain.com/api/health
 
# Verify Linear webhook configuration
# Go to Linear Settings → Integrations → Webhooks
# Ensure the webhook URL is correct and accessible
 
# Check GitHub Actions logs
# Go to repository → Actions → Select workflow → View logs

Deployment Failures

Symptoms

  • Vercel deployments failing
  • Environment variables not loading
  • Build errors in deployment logs

Diagnosis Steps

  1. Check Environment Variables

    • Verify all required variables are set in Vercel
    • Check for typos in variable names
    • Ensure variables are set for the correct environment

  2. Review Build Logs

    • Check Vercel deployment logs
    • Look for specific error messages
    • Verify build commands are correct

  3. Check Repository Status

    • Ensure the repository is accessible
    • Verify the branch exists
    • Check for any merge conflicts

Solutions

# Verify environment variables in Vercel
# Go to Project Settings → Environment Variables
# Ensure all variables are set for Production, Preview, and Development
 
# Check build configuration
# Verify vercel.json and package.json are correct
# Ensure build scripts are properly configured
 
# Test local build
npm run build
# This should complete without errors

Memory Service Issues

Symptoms

  • Workflow context not persisting
  • AI agents losing conversation history
  • Memory-related errors in logs

Diagnosis Steps

  1. Check Zep Service Status

    • Verify Zep service is running
    • Check API endpoint accessibility
    • Verify authentication credentials

  2. Check Memory Collections

    • Ensure required collections exist
    • Verify collection permissions
    • Check for collection size limits

  3. Review API Calls

    • Check network tab for failed requests
    • Verify API key is valid
    • Check rate limiting status

Solutions

# Test Zep API connectivity
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-zep-instance.com/api/v1/collections
 
# Verify environment variables
echo $VITE_ZEP_API_URL
echo $VITE_ZEP_API_KEY
 
# Check Zep service logs
# Look for any error messages or connection issues

GitHub Integration Problems

Symptoms

  • Pull requests not being created
  • Branches not being created
  • GitHub Actions not triggering

Diagnosis Steps

  1. Check GitHub Token Permissions

    • Verify token has required scopes
    • Check if token has expired
    • Ensure token has access to the repository

  2. Verify Repository Configuration

    • Check if repository exists and is accessible
    • Verify branch protection rules
    • Check for any repository restrictions

  3. Review GitHub Actions

    • Ensure workflows are properly configured
    • Check for any syntax errors in YAML files
    • Verify workflow triggers are correct

Solutions

# Test GitHub API access
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO
 
# Verify token scopes
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/user
 
# Check repository access
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/branches

🔧 Debug Tools

Browser Console

Enable Debug Logging

// Add to your application code
localStorage.setItem('debug', 'workflow:*');
 
// Or set in browser console
localStorage.setItem('debug', 'workflow:*');
location.reload();

Common Debug Commands

// Check workflow state
console.log(window.workflowState);
 
// View available services
console.log(window.workflowServices);
 
// Check memory service status
console.log(window.memoryService);
 
// View webhook history
console.log(window.webhookHistory);

Network Tab Analysis

Monitor API Calls

  1. Open Browser DevTools → Network tab
  2. Filter by "Fetch/XHR" requests
  3. Look for failed requests (red status codes)
  4. Check request/response payloads
  5. Verify authentication headers

Common Error Patterns

  • 401 Unauthorized: Authentication token expired or invalid
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Endpoint or resource doesn't exist
  • 429 Too Many Requests: Rate limiting exceeded
  • 500 Internal Server Error: Server-side issue

State Inspection

React DevTools

  1. Install React Developer Tools browser extension
  2. Open DevTools → Components tab
  3. Navigate to AutomatedWorkflowUI component
  4. Inspect state and props
  5. Check for any error states or loading issues

Redux DevTools (if using Redux)

  1. Install Redux DevTools extension
  2. Open DevTools → Redux tab
  3. Monitor state changes
  4. Check for any failed actions
  5. Review action payloads and error states

📊 Performance Issues

Slow Workflow Execution

Common Causes

  1. API Rate Limiting: Too many requests to external services
  2. Large Data Processing: Handling large datasets without optimization
  3. Sequential Operations: Steps running one after another instead of parallel
  4. Network Latency: Slow connections to external services
  5. Resource Constraints: Insufficient CPU/memory resources

Optimization Strategies

{
  "name": "Optimized Workflow",
  "steps": [
    {
      "name": "parallel_tasks",
      "parallel": true,
      "steps": [
        {"name": "task1", "action": "service.action1"},
        {"name": "task2", "action": "service.action2"},
        {"name": "task3", "action": "service.action3"}
      ]
    },
    {
      "name": "batch_processing",
      "action": "service.batch_process",
      "params": {
        "batch_size": 100,
        "concurrent_batches": 5
      }
    }
  ]
}

Memory Leaks

Symptoms

  • Application becomes slower over time
  • Browser memory usage increases
  • Workflows fail after running multiple times

Prevention

// Clean up event listeners
useEffect(() => {
  const handleWebhook = (data) => {
    // Process webhook data
  };
  
  webhookService.on('webhook', handleWebhook);
  
  return () => {
    webhookService.off('webhook', handleWebhook);
  };
}, []);
 
// Clear intervals and timeouts
useEffect(() => {
  const interval = setInterval(() => {
    // Periodic task
  }, 5000);
  
  return () => clearInterval(interval);
}, []);

🚨 Emergency Procedures

Workflow Rollback

Immediate Actions

  1. Stop All Workflows

    # Disable webhook endpoints temporarily
# Comment out webhook configurations in Linear
# Pause GitHub Actions workflows

  2. Revert Recent Changes

    # Revert to last known good commit
git revert HEAD
 
# Or reset to specific commit
git reset --hard COMMIT_HASH

  3. Restore Database State

    -- Restore from backup if available
-- Or manually fix corrupted data
UPDATE workflows SET status = 'failed' WHERE status = 'in_progress';

Service Recovery

Linear Service

  1. Check Linear status page for outages
  2. Verify API key permissions
  3. Test webhook endpoint accessibility
  4. Recreate webhook if necessary

GitHub Service

  1. Check GitHub status page
  2. Verify personal access token
  3. Check repository permissions
  4. Review branch protection rules

Vercel Service

  1. Check Vercel status page
  2. Verify project configuration
  3. Check environment variables
  4. Review deployment settings

📞 Getting Help

Self-Service Resources

  • Documentation: Check this troubleshooting guide
  • Community Forum: Discord (opens in a new tab)
  • GitHub Issues: Report bugs and request features
  • Knowledge Base: Search for similar issues

Escalation Process

  1. Check Documentation: Review relevant sections
  2. Search Community: Look for similar issues
  3. Create Issue: Document the problem with details
  4. Contact Support: Reach out to the development team

Issue Reporting Template

## Issue Description
[Describe what you're experiencing]
 
## Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Step 3]
 
## Expected Behavior
[What should happen]
 
## Actual Behavior
[What actually happens]
 
## Environment
- Browser: [Browser and version]
- OS: [Operating system]
- Workflow Type: [Type of workflow]
- Error Messages: [Any error messages]
 
## Additional Context
[Any other relevant information]

🔮 Prevention Strategies

Regular Maintenance

  1. Monitor System Health: Set up health checks
  2. Update Dependencies: Keep packages up to date
  3. Review Logs: Regularly check for errors
  4. Test Workflows: Run test workflows periodically

Best Practices

  1. Use Environment Variables: Never hardcode sensitive data
  2. Implement Retry Logic: Handle transient failures gracefully
  3. Add Timeouts: Prevent workflows from hanging indefinitely
  4. Monitor Resources: Track API usage and costs

Still having issues? Reach out to the community or create a detailed issue report with the template above.

Workflow ExamplesAPI Reference