Troubleshooting

This section provides solutions to common issues you might encounter while using OpsSquad.ai.

Quick Diagnostics

Before diving into specific issues, run these diagnostic checks:

Node Diagnostics

# Check node status
opssquad node status

# Validate installation
opssquad node validate

# View recent logs
opssquad node logs --lines=50

Network Diagnostics

# Test connectivity to OpsSquad.ai
nc -zv socket.opssquad.ai 9000

# Check DNS resolution
nslookup socket.opssquad.ai

Issue Categories

Section	Description
CLI Issues	Problems with installation, commands, or node management.
Dashboard Issues	Problems with the web interface, login, or squad management.
Chat Issues	Problems with the chat interface, agents not responding, or connectivity.

Most Common Issues

Node Won't Connect

Symptoms: Node starts but shows "Disconnected"

Quick Fix:

Check network access to socket.opssquad.ai:9000
Verify firewall allows outbound TCP on port 9000
Check credentials in configuration file

Detailed solution →

Symptoms: Login page shows error or doesn't redirect

Quick Fix:

Clear browser cache and cookies
Try incognito/private mode
Check if email is verified

Detailed solution →

Chat Not Receiving Responses

Symptoms: Messages sent but no response from agent

Quick Fix:

Check if there's a pending approval
Verify the agent is linked to an online node
Verify the selected squad has active agents
Refresh the page

Detailed solution →

Error Messages

"Connection Refused"

Context	Meaning	Solution
CLI	Network blocked	Check firewall
Dashboard	API unreachable	Check status page
Chat	WebSocket failed	Refresh browser

"Authentication Failed"

Context	Meaning	Solution
CLI	Invalid API key	Regenerate credentials
Dashboard	Session expired	Log in again
Chat	Token invalid	Clear cache, re-login

"Insufficient Credits"

Context	Meaning	Solution
Deployment	No credits	Top up wallet
Runtime	Credits exhausted	Top up or wait for grant

Diagnostic Tools

Node Validation

Run a comprehensive check:

opssquad node validate

This checks:

Configuration file exists and is valid
Node binary is present
Network connectivity works
Credentials are correct
Required permissions exist

Status Check

Get current node state:

opssquad node status

Expected output:

Node Status:  Online
Connection:   Connected
Version:      1.0.0
Uptime:       2h 34m 12s

Log Analysis

View logs for errors:

# View last 100 lines
opssquad node logs

# Stream logs in real-time
opssquad node logs --follow

Look for:

ERROR - Critical issues
WARN - Potential problems
disconnect - Connection issues
timeout - Network problems

System Status

Check the OpsSquad.ai platform status:

Status Page: status.opssquad.ai
Twitter: @opssquadai

The status page shows:

Platform health
Scheduled maintenance
Incident history

Getting Help

If you can't resolve the issue:

Support Channels

Channel	Best For	Response Time
Documentation	Self-service	Instant
Discord	Community help	Minutes-hours
Email	Complex issues	24 hours
Priority Support	Enterprise	< 4 hours

Before Contacting Support

Gather this information:

Output of opssquad node validate
Output of opssquad node logs --lines=100
Your operating system and version
Steps to reproduce the issue
Screenshots if applicable

Contact Information

Email: [email protected]
Discord: discord.gg/opssquad
GitHub: github.com/opssquad/opssquad-cli-tool/issues

Preventing Issues

Keep Updated

Always run the latest version:

opssquad upgrade

Updates include:

Bug fixes
Security patches
New features
Performance improvements

Monitor Health

Set up proactive monitoring:

Enable status alerts in Settings
Monitor node connection status
Check agent-node link status
Review logs periodically

Follow Best Practices

Use strong, unique credentials
Keep API keys secure
Test in staging before production
Document your configurations

Troubleshooting

On this page