Troubleshooting Guide

Common issues and solutions when using Hydra.

Connection Issues

MCP Server Not Connecting

Symptoms:

• IDE shows "Hydra not available"
• "Connection refused" errors
• Workflows not listed

Solutions:

Firewall Blocking Connections

If you're on a corporate network:

1. Ensure these domains are allowed:

   • hydra.opiusai.com (web dashboard)
   • *.execute-api.us-west-2.amazonaws.com (API Gateway endpoints)

2. Port 443 (HTTPS) must be open

3. HTTP POST requests must be permitted (MCP uses JSON-RPC over HTTP)

Workflow Execution Issues

"Workflow Not Found" Error

Causes:

• Workflow was deleted
• Using wrong account
• Workflow is private and you don't have access

Solutions:

1. Check your Dashboard - is the workflow listed?
2. Verify account - sign out and back in
3. For subscribed workflows - check if owner unpublished it
4. Refresh your IDE's Hydra connection

Steps Executing Out of Order

Cause: Missing or incorrect depends_on configuration

Solution:

Check your manifest's dependency chain:

{
  "steps": [
    { "id": "step1", "name": "First" },
    { "id": "step2", "depends_on": ["step1"] },  // ✓ Correct
    { "id": "step3", "depends_on": ["step1", "step2"] }  // ✓ Multiple deps OK
  ]
}

Workflow Hangs or Times Out

Possible causes:

1. Step taking too long - Complex analysis on large codebases
2. Network interruption - Connection dropped mid-execution
3. IDE rate limiting - Too many concurrent requests

Solutions:

1. Break into smaller steps - Large tasks should be split
2. Add timeouts to your manifest:

   {
     "config": {
       "step_timeout_ms": 60000
     }
   }
3. Check IDE logs for specific errors

Step Produces No Output

Causes:

• Action not supported by current adapter
• Missing required parameters
• Empty file/input provided

Solutions:

1. Verify action compatibility - See Adapters Reference
2. Add required parameters:

   {
     "action": "analyze_code",
     "parameters": {
       "files": ["src/main.ts"],  // Required for some actions
       "focus": "security issues"
     }
   }

Authentication Issues

"Unauthorized" or 401 Errors

Solutions:

1. Sign out and back in at hydra.opiusai.com
2. Clear browser cookies for opiusai.com
3. Regenerate API key if using Codex
4. Check account status - ensure not suspended

Session Expired

Sessions expire after 7 days of inactivity.

Solution: Simply sign back in at the dashboard.

OAuth/GitHub Sign-in Fails

1. Revoke and re-authorize Hydra in GitHub Settings → Applications
2. Clear cookies and try again
3. Try email sign-in as backup

Builder Issues

Save Button Disabled

The save button is disabled when:

1. No changes made - The workflow is already saved
2. Validation errors - Fix errors shown in red
3. Not signed in - Sign in to save

Hover over the button to see the specific reason.

Validation Errors

Common validation errors:

Nodes Not Connecting

In the visual builder:

1. Drag from output port (right side) to input port (left side)
2. Ensure step IDs are unique
3. Check for existing connections - delete if needed

Marketplace Issues

Can't Find My Published Workflow

After publishing, workflows may take up to 5 minutes to appear in search.

Also check:

• Workflow visibility is set to "Public"
• Category and tags are set (improves discoverability)
• Search is using correct keywords

Fork Not Working

Causes:

• Already forked this workflow (can't fork twice)
• Workflow owner disabled forking
• Not signed in

Solutions:

1. Check My Workflows - you may already have a fork
2. Sign in if prompted
3. Contact workflow owner if forking seems disabled

Rating/Review Not Appearing

Reviews require:

• You must have used the workflow (fork or subscribe)
• Review text must be at least 10 characters
• One review per workflow per user

Performance Issues

Slow Dashboard Loading

1. Clear browser cache
2. Check internet connection
3. Try a different browser
4. Reduce number of workflows (archive unused ones)

IDE Feels Slow After Adding Hydra

1. Limit active MCP connections - disable unused servers
2. Increase IDE memory if available
3. Check for conflicting extensions

Getting More Help

Check Status Page

Visit status.hydra.opiusai.com (opens in a new tab) for system status and incidents.

Community Support

Have questions or found a bug? Email us at support@opiusai.com with:

• Your account email
• Steps to reproduce the issue
• Any error messages

Contact Support

For account issues or urgent problems:

• Email: support@opiusai.com
• Include: Your account email, error messages, steps to reproduce

FAQ

Is Hydra free?

Hydra offers a free tier with:

• Up to 5 workflows
• 1 deployment
• 500 MCP connections per month
• Up to 20 subscriptions

See Pricing (opens in a new tab) for Pro, Team, and Enterprise plans.

Which IDEs are supported?

Currently:

• Claude Code - Full support with sub-agents
• Cursor - Full support with Composer
• Codex CLI - Full support via API

Coming soon: VS Code extension, JetBrains plugin

Can I use Hydra offline?

No, Hydra requires an internet connection to:

• Authenticate users
• Serve workflow manifests
• Sync with marketplace

However, once a workflow is loaded into your IDE's context, execution uses your IDE's AI capabilities.

How do I delete my account?

Via Dashboard:

1. Go to Settings → Account
2. Scroll to "Danger Zone"
3. Click Delete Account
4. Confirm the action

Via API:

DELETE /users/me

This performs a complete cascade deletion of all your data including workflows, deployments, subscriptions, and billing records.

Can I export my workflows?

Yes! Each workflow can be exported as:

• JSON manifest - Full HMS specification
• YAML - Alternative format

From the Builder, click Export → Choose format.