Troubleshooting

This guide covers common issues you may encounter while using the Agents App and how to resolve them.

Common Issues

Issue: Dashboard Shows No Active Workers

Symptoms:

• Active Workers count shows 0
• Tasks remain in queue indefinitely
• No activity in the Activity Feed

Cause: Workers may be offline, crashed, or not configured properly.

Solution:

1. Navigate to Workers in the sidebar
2. Check if any workers are listed
3. Verify worker status (Active, Idle, or Inactive)
4. If workers show as Inactive:
   • Check that the agent service is running
   • Verify network connectivity between agents and FlowState
   • Review worker logs for error messages
5. Contact your administrator if no workers are configured

Issue: Tasks Stuck in "In Progress"

Symptoms:

• Task shows "In Progress" for an extended period
• No new logs appearing for the task
• Worker appears idle despite assigned task

Cause: The agent may have crashed during execution, or there's a communication issue.

Solution:

1. Navigate to the task detail page
2. Check the Conversation tab for any agent queries awaiting response
3. Review the Logs for error messages
4. If the agent is unresponsive:
   • Check worker status on the Workers page
   • Consider manually resetting the task status
   • Review system logs for crash reports
5. If blocked by a human response:
   • Respond to the agent's query in the Conversation tab
   • The task will be re-queued for processing

Issue: Approvals Not Appearing

Symptoms:

• Agent completes work but no approval request appears
• Approval count remains at 0

Cause: The task may not be configured to require approval, or there's a data sync issue.

Solution:

1. Verify the task is configured to require approval
2. Check the task detail page for completion status
3. Refresh the Approvals page
4. If using offline mode, check for sync status:
   • Look for the sync indicator in the app
   • Wait for pending changes to replicate
5. Check the Logs page for any error messages related to approval creation

Issue: Log Viewer Shows No Entries

Symptoms:

• Log viewer displays empty state
• "No logs found" message appears
• Filters return no results

Cause: Logs may not have been generated yet, or filters are too restrictive.

Solution:

1. Remove all filters to see if any logs exist
2. Expand the time range being viewed
3. Check if:
   • Agents have executed any tasks
   • You're viewing logs for the correct workspace
   • Log level filter is set appropriately (include debug/info)
4. If logs should exist but don't appear:
   • Check network connectivity
   • Verify database sync status
   • Contact support if issue persists

Issue: Codebase Operations Failing

Symptoms:

• Unable to create new codebases
• Error message when editing codebase
• Codebase list not loading

Cause: Permission issues, validation errors, or network problems.

Solution:

1. Verify you have permissions to manage codebases
2. Check that all required fields are filled correctly
3. Ensure the workspace context is set properly
4. Try refreshing the page
5. Check browser console for error details
6. Verify network connectivity to FlowState services

Issue: Agent Responses Not Updating Task

Symptoms:

• You reply to an agent query but task doesn't progress
• Task remains in same status after response
• Agent doesn't pick up the updated task

Cause: The response may not have saved correctly, or the agent queue needs refresh.

Solution:

1. Verify your response was saved (check the Conversation tab)
2. Ensure the task status was reset to allow agent pickup
3. Check that:
   • The response form submitted successfully
   • No error messages appeared
   • The conversation shows your reply
4. If response appears but task doesn't progress:
   • Verify workers are active
   • Check for any blocking issues in task metadata
   • Review logs for processing errors

Issue: Performance Issues or Slow Loading

Symptoms:

• Pages take a long time to load
• Interface feels sluggish
• Operations timeout

Cause: Large data sets, network latency, or browser resource constraints.

Solution:

1. Apply filters to reduce data being loaded:
   • Filter tasks by status
   • Limit log results by date range
   • Focus on specific codebases
2. Clear browser cache and cookies
3. Check network connectivity and speed
4. Close other resource-intensive tabs
5. Try a different browser
6. If persists, report to support with:
   • Approximate number of records
   • Browser and version
   • Actions that trigger slowness

Issue: Approval Actions Not Working

Symptoms:

• Approve/Reject buttons don't respond
• Error message when taking action
• Approval status doesn't update

Cause: Permission issues, concurrent edits, or network problems.

Solution:

1. Verify you have permission to approve items
2. Check if another user modified the approval
3. Refresh the page and try again
4. Ensure you're logged in with an active session
5. Check for error messages in the dialog
6. If using comments, ensure they're valid (not too long)

Debugging with Logs

The Agents App provides comprehensive logging for debugging issues.

Accessing Logs

1. Navigate to Logs in the sidebar
2. Use filters to narrow down:
   • Level: debug, info, warn, error, critical
   • Category: Filter by log category
   • Search: Find specific messages

Interpreting Log Entries

Log Metadata

Expand log entries to see additional metadata:

• Command: The command that was executed
• Exit Code: Process exit status (0 = success)
• Duration: How long the operation took
• Error: Detailed error information if applicable

Getting Help

If you can't resolve your issue:

1. Check the FAQ for additional answers
2. Search existing support tickets for similar issues
3. Gather diagnostic information:
   • Description of the issue
   • Steps to reproduce
   • Screenshots of the problem
   • Relevant log entries
   • Browser and device information
4. Contact support with the gathered information

Reporting Bugs

When reporting bugs, include:

Issue Summary: Brief description

Steps to Reproduce:
1. Step one
2. Step two
3. Step three

Expected Behavior: What should happen

Actual Behavior: What actually happens

Environment:
- Browser: Chrome 120
- FlowState Version: 1.0.0
- Operating System: macOS 14.0

Logs/Screenshots: [Attach relevant files]