Troubleshooting

Quick Diagnostics

Start with the built-in health check:

astromeshctl doctor

It asks the daemon (GET /v1/system/doctor) for its checks: runtime initialized, each provider’s health, and each configured peer.

For a quick status overview:

astromeshctl status

---

Common Issues (All Platforms)

Daemon does not start

Step 1: Check the daemon logs for errors.

• Linux: sudo journalctl -u astromeshd -n 50
• macOS: tail -n 50 /Library/Logs/Astromesh/astromeshd.err.log
• Windows: run astromeshd --foreground in a terminal to see the output (the service writes no log file)

Step 2: Validate your configuration:

astromeshctl config validate --path /etc/astromesh

Step 3: Check for port conflicts. Another process may be using port 8000:

• Linux/macOS: sudo ss -tlnp | grep 8000 or lsof -i :8000
• Windows: netstat -ano | findstr 8000

Change the port in runtime.yaml or stop the conflicting process.

API returns 503 / connection refused

The daemon may still be starting. Wait 10–30 seconds, then:

astromeshctl status
curl http://localhost:8000/v1/health

If the daemon is running but the API is not responding, check if the api service is enabled in runtime.yaml:

spec:
  services:
    api: true    # Must be true

Configuration syntax error

ERROR: Failed to parse /etc/astromesh/runtime.yaml: expected ':', line 5

Fix YAML syntax issues, then validate:

astromeshctl config validate --path /etc/astromesh
sudo systemctl restart astromeshd  # Linux

Provider connection failures

ERROR: Provider 'ollama' health check failed: Connection refused

Verify the provider is reachable:

# Ollama
curl http://localhost:11434/api/tags

# OpenAI
curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models

The model router circuit breaker opens after 3 consecutive failures (60-second cooldown). Check provider status:

astromeshctl providers list
astromeshctl doctor

Agent not found

{"detail": "Agent 'myagent' not found"}

Verify the agent YAML file exists and is valid:

ls /etc/astromesh/agents/           # Linux/macOS
ls "C:\ProgramData\Astromesh\config\agents\"  # Windows

astromeshctl agents list
astromeshctl config validate --path /etc/astromesh

Agents load at startup; restart the daemon after adding one:

sudo systemctl restart astromeshd   # Linux

Permission errors

PermissionError: [Errno 13] Permission denied: '/var/lib/astromesh/data/...'

Fix ownership (Linux; on macOS the user is _astromesh):

sudo chown -R astromesh:astromesh /var/lib/astromesh
sudo chown -R astromesh:astromesh /var/log/astromesh

Stale PID file (Linux/macOS)

ERROR: PID file exists but process is not running

The daemon did not shut down cleanly. Remove the stale PID file:

sudo rm /var/lib/astromesh/astromeshd.pid
sudo systemctl restart astromeshd   # Linux

---

Linux-Specific

systemd service fails to start

sudo systemctl status astromeshd
sudo journalctl -u astromeshd -n 100 --no-pager

Common causes:

Error	Fix
Address already in use	Change port in runtime.yaml or stop conflicting process
Permission denied	Check file ownership: sudo chown -R astromesh:astromesh /var/lib/astromesh
No such file or directory	Re-run sudo astromeshctl init
Failed to parse config	Run astromeshctl config validate and fix YAML

View systemd logs

# Follow live
sudo journalctl -u astromeshd -f

# Last 100 lines
sudo journalctl -u astromeshd -n 100

# Only errors
sudo journalctl -u astromeshd -p err

# Full output without pager
sudo journalctl -u astromeshd --no-pager

SELinux denials (RHEL/Fedora)

# Check for SELinux denials
sudo ausearch -c astromeshd -m avc --ts recent

# Generate and apply local policy
sudo ausearch -c astromeshd -m avc | audit2allow -M astromesh_local
sudo semodule -i astromesh_local.pp

---

macOS-Specific

launchd service does not start

# Check launchd status
sudo launchctl list | grep astromesh

# View plist errors
sudo launchctl print system/com.astromesh.daemon

# Check logs
tail -n 100 /Library/Logs/Astromesh/astromeshd.err.log

Gatekeeper blocks the binary

sudo xattr -d com.apple.quarantine /usr/local/bin/astromeshd
sudo xattr -d com.apple.quarantine /usr/local/bin/astromeshctl

Or: System Settings > Privacy & Security > click “Allow Anyway”.

Service not loading on boot

Verify the plist is in the system LaunchDaemons directory (not user LaunchAgents):

ls /Library/LaunchDaemons/com.astromesh.daemon.plist

# Reload
sudo launchctl unload /Library/LaunchDaemons/com.astromesh.daemon.plist
sudo launchctl load /Library/LaunchDaemons/com.astromesh.daemon.plist

---

Windows-Specific

Service fails to start

# Check service status (the service is named astromeshd)
Get-Service astromeshd

# Not listed? install.ps1 does not register it — see the Windows install guide

PowerShell execution policy blocks install

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1

Port 8000 in use

netstat -ano | findstr :8000
# Find the PID, then:
Stop-Process -Id <PID>

Or change the port in C:\ProgramData\Astromesh\config\runtime.yaml.

astromeshctl not found after install

The installer adds C:\Program Files\Astromesh\venv\Scripts\ to the system PATH. Open a new terminal (the PATH update takes effect in new sessions):

# Or add manually to current session:
$env:Path += ";C:\Program Files\Astromesh\venv\Scripts"

---

Log Locations

Platform	Log Path
Linux	journalctl -u astromeshd
macOS	/Library/Logs/Astromesh/astromeshd.out.log, astromeshd.err.log
Windows	none — run astromeshd --foreground to see output

---

Getting More Help

• Run astromeshctl doctor --json and share the output
• Check GitHub Issues
• Review the Configuration reference for schema errors
• Check the CLI Reference for command usage