CLI Troubleshooting

This guide covers common issues you may encounter with the FixPanic CLI and how to resolve them.

Diagnostic Commands

Before troubleshooting, run these commands to gather information:

# Validate installation
fixpanic agent validate

# Check agent status
fixpanic agent status

# View recent logs
fixpanic agent logs --lines=50

Common Issues

Agent Won't Start

Symptoms:

• fixpanic agent start completes but agent shows as stopped
• Status shows "Inactive" or "Failed"

Solutions:

1. Run validation:

   fixpanic agent validate

   This identifies configuration or permission issues.

2. Check logs for errors:

   fixpanic agent logs

   Look for error messages indicating the root cause.

3. Verify configuration exists:

   # System installation
   cat /etc/fixpanic/agent.yaml
   
   # User installation
   cat ~/.config/fixpanic/agent.yaml

4. Check binary exists:

   # System installation
   ls -la /usr/local/lib/fixpanic/
   
   # User installation
   ls -la ~/.local/lib/fixpanic/

Connectivity Problems

Symptoms:

• Agent starts but shows "Disconnected"
• "Connection refused" or "timeout" errors in logs
• Agent repeatedly reconnecting

Solutions:

1. Test network connectivity:

   # Check if you can reach the platform
   nc -zv socket.fixpanic.com 9000
   
   # Alternative test
   curl -v telnet://socket.fixpanic.com:9000

   If this fails, you have a network/firewall issue.

2. Check firewall rules:

   Ensure outbound TCP connections on port 9000 are allowed:

   # UFW (Ubuntu)
   sudo ufw status
   
   # iptables
   sudo iptables -L -n | grep 9000
   
   # firewalld (CentOS/RHEL)
   sudo firewall-cmd --list-all

3. Check DNS resolution:

   nslookup socket.fixpanic.com
   dig socket.fixpanic.com

4. Check for proxy interference:

   The agent's TCP connection may not work through HTTP proxies. Try disabling proxy settings:

   unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
   fixpanic agent restart

Permission Errors

Symptoms:

• "Permission denied" errors
• Cannot read/write configuration files
• Service fails to start

Solutions:

System Installation (Root)

If you installed with sudo, always use sudo for management commands:

sudo fixpanic agent status
sudo fixpanic agent start
sudo fixpanic agent logs

Check file permissions:

# Configuration should be readable by root
sudo ls -la /etc/fixpanic/

# Logs directory should be writable
sudo ls -la /var/log/fixpanic/

Fix permissions if needed:

sudo chown -R root:root /etc/fixpanic/
sudo chmod 600 /etc/fixpanic/agent.yaml
sudo chmod 755 /var/log/fixpanic/

User Installation (Non-Root)

If you installed as a regular user, do not use sudo:

# Correct - no sudo
fixpanic agent status

# Incorrect - will cause permission conflicts
sudo fixpanic agent status  # Don't do this!

Check file permissions:

ls -la ~/.config/fixpanic/
ls -la ~/.local/lib/fixpanic/
ls -la ~/.local/log/fixpanic/

Configuration Invalid

Symptoms:

• Validation fails with "invalid configuration"
• Agent won't start due to config errors

Solutions:

1. Check YAML syntax:

   # Install yamllint
   pip install yamllint
   
   # Validate config
   yamllint /etc/fixpanic/agent.yaml

2. Verify required fields:

   The configuration must have agent_id and api_key:

   app:
     agent_id: "your-agent-id"  # Required
     api_key: "your-api-key"    # Required

3. Check for special characters:

   If your API key contains special characters, wrap it in quotes:

   app:
     api_key: "sk_live_key+with/special=chars"

4. Regenerate configuration:

   If config is corrupted, reinstall:

   fixpanic agent uninstall --force
   fixpanic agent install --agent-id="your-id" --api-key="your-key"

macOS Security Warnings

Symptoms:

• "fixpanic cannot be opened because the developer cannot be verified"
• Binary blocked by Gatekeeper

Solutions:

Using System Preferences

1. Open System Preferences (or System Settings on macOS Ventura+)
2. Go to Security & Privacy (or Privacy & Security)
3. Under the General tab, you should see a message about fixpanic being blocked
4. Click Open Anyway or Allow Anyway
5. Try running the command again

Using Command Line

Remove the quarantine attribute:

sudo xattr -d com.apple.quarantine /usr/local/bin/fixpanic
sudo xattr -d com.apple.quarantine /usr/local/lib/fixpanic/*

Service Not Starting on Boot

Symptoms:

• Agent runs when started manually but doesn't start on boot
• Systemd service not enabled

Solutions:

Check if the service is enabled:

sudo systemctl is-enabled fixpanic-connectivity-layer

Enable it:

sudo systemctl enable fixpanic-connectivity-layer

Check service status:

sudo systemctl status fixpanic-connectivity-layer

View service logs:

sudo journalctl -u fixpanic-connectivity-layer -f

Agent Keeps Disconnecting

Symptoms:

• Frequent "reconnecting" messages in logs
• Agent status fluctuates between Connected/Disconnected

Possible Causes:

1. Unstable network connection - Check network stability
2. Firewall timeout - Some firewalls close idle connections
3. Resource exhaustion - Check CPU/memory usage

Solutions:

# Check for network issues
ping -c 10 socket.fixpanic.com

# Check system resources
top -bn1 | head -20

# Check for connection resets in logs
fixpanic agent logs | grep -i "disconnect\|reconnect\|error"

Getting Help

If you cannot resolve the issue:

• Email Support: Contact [email protected] with output of fixpanic agent validate and fixpanic agent logs, plus your operating system and version.
• Community Discord: Join discord.gg/fixpanic for real-time help from the community.
• GitHub Issues: Report bugs at github.com/fixpanic/fixpanic-cli-tool/issues.

Next Steps

• Commands Reference - Review all available CLI commands.
• Configuration - Learn about configuration options.