Agent Troubleshooting

This guide covers common issues with FlightStack build agents and their solutions.

Connection Issues

Agent Shows as Offline

Symptoms: Agent shows 🔴 Offline in FlightStack despite running.

Causes & Solutions:

Agent not running

flightstack agent status
# If stopped, start it:
flightstack agent start

Network connectivity

# Test API connectivity
curl https://api.flightstack.dev/health

Firewall blocking
- Ensure outbound HTTPS (port 443) is allowed
- Check corporate proxy settings

Invalid token

# Re-register to get a new token
flightstack agent register

Connection Timeout

Connection failed
Error: Connection timed out

Solutions:

Check internet connectivity
Verify DNS resolution: nslookup api.flightstack.dev
Check for proxy requirements
Try: curl -v https://api.flightstack.dev/health

Heartbeat Failures

Heartbeat failed: Connection refused

The agent will retry automatically. If persistent:

Restart the agent
Check if API is undergoing maintenance
Verify your token is still valid

Build Failures

Build Stuck in “Queued”

Causes:

No online agents with matching capabilities
All agents are busy
Agent disk space too low

Solutions:

# Check agent status
flightstack agent list

# Verify agent is online and has capacity
flightstack agent status

Flutter Not Found

Error: flutter: command not found

Solution: Ensure Flutter is in the agent’s PATH:

# Find Flutter
which flutter

# Add to shell profile
echo 'export PATH="$PATH:/path/to/flutter/bin"' >> ~/.zshrc
source ~/.zshrc

# Verify
flutter doctor

# Restart agent
flightstack agent stop
flightstack agent start

Xcode Build Errors

“No provisioning profile”

# Check profiles
security find-identity -v -p codesigning

“Xcode not found”

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

“License not accepted”

sudo xcodebuild -license accept

Android Build Errors

“SDK not found”

# Set ANDROID_HOME
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

# Accept licenses
flutter doctor --android-licenses

“Build tools not found”

sdkmanager "build-tools;34.0.0"

CocoaPods Errors

Error: CocoaPods not installed

sudo gem install cocoapods
pod setup

Error: CDN: trunk URL couldn't be downloaded

pod repo remove trunk
pod setup

Resource Issues

Disk Space Low

Agent paused: Insufficient disk space

Solutions:

Free up disk space

Clear Flutter/Gradle caches:

flutter clean
rm -rf ~/.gradle/caches/
rm -rf ~/Library/Developer/Xcode/DerivedData/

Remove old builds:
Terminal window
```
rm -rf /tmp/flightstack-*
```

Out of Memory

Large Flutter projects can consume significant memory.

Solutions:

Close unnecessary applications
Increase swap space (Linux)
Limit Gradle memory in gradle.properties:
```
org.gradle.jvmargs=-Xmx4g
```

Startup Issues

Service Won’t Start

Check logs:

tail -100 ~/.flightstack/agent.log

Common causes:

Agent not registered
Invalid configuration
Permission issues

Auto-Start Not Working

macOS:

# Check if loaded
launchctl list | grep flightstack

# Manually load
launchctl load ~/Library/LaunchAgents/com.flightstack.agent.plist

Linux:

# Check service status
systemctl --user status flightstack-agent

# Check for errors
journalctl --user -u flightstack-agent -n 50

Getting Help

If you’re still stuck:

Check agent logs
Terminal window
```
tail -f ~/.flightstack/agent.log
```
Run Flutter diagnostics
Terminal window
```
flutter doctor -v
```
Join our Discord Get help from the community at discord.gg/flightstack
Open an issue Report bugs at github.com/voostack/flightstack/issues