Runtime Sync Troubleshooting

This guide helps you diagnose and resolve common issues with runtime sync between Helm Cloud and self-hosted local runtime modes.

Understanding Runtime Status

Status Badge

The runtime status badge appears in your session workspace header. It shows:

Element	Meaning
Mode Icon	☁️ Cloud or 💻 Local
Health Dot	🟢 Healthy, 🟡 Warning, 🔴 Error
Sync Indicator	✓ Synced, ↻ Syncing, ⚠ Conflict, ✗ Error

Click the badge to see detailed status information and remediation steps.

Health States

State	Description	Action Required
Healthy	Runtime is connected and synced	None
Warning	Minor issue (sync pending, brief disconnect)	Usually resolves automatically
Error	Runtime disconnected or sync failed	Follow remediation steps

Common Issues

Local Agent Offline

Symptoms:

• Badge shows yellow/red dot
• Status shows "Disconnected" or "Agent offline"
• Sessions fail with "No runtime available"

Remediation Steps:

Verify agent is running:

helm-agent status

If not running, start it:

helm-agent start --token YOUR_TOKEN

Check network connection:

- Ensure outbound connections to api.helm-ade.dev are allowed - Verify port 443 (HTTPS/WebSocket) is not blocked

Restart the agent:

helm-agent restart

Check agent logs for errors:

helm-agent logs

Re-register if needed:

- Open Project Settings > Local Agent - Click "Register New Agent" - Use the new token to restart your agent

Sync Conflicts

Symptoms:

• Badge shows ⚠ conflict indicator
• Sync status shows "Conflict"
• Popover lists conflicting files

Remediation Steps:

Review conflicting files:

- Click the status badge to see the file list - Note the conflict guidance provided

Resolve locally:

- Pull the latest changes to your local environment - Open conflicting files and resolve differences - Commit your resolved changes

Retry sync:

- Click "Push" in the sync panel - Or wait for automatic sync to retry Prevention:

• Coordinate with team members before making overlapping changes
• Use smaller, more frequent commits
• Consider using branches for larger changes

Sync Errors

Symptoms:

• Badge shows ✗ error indicator
• Sync status shows "Error"
• Error message displayed in popover

Common Causes & Solutions:

Error	Cause	Solution
"No GitHub repository configured"	Repository not bound	Configure repository in Project Settings
"You do not have access to this repository"	Missing GitHub permissions	Request repo access from admin
"Authentication failed"	Token expired or revoked	Re-authenticate with GitHub
"Network error"	Connectivity issue	Check internet connection
"Repository not found"	Repo deleted or renamed	Update repository URL in settings

Sync Not Updating

Symptoms:

• Changes made but sync shows "Idle"
• Last sync time is stale
• Other team members don't see your changes

Remediation Steps:

Manual refresh:

- Click the refresh button on the status badge - Or click the badge to open the detailed view

Force sync:

- Open Project Settings > GitHub Sync - Click "Push" to upload your changes - Click "Pull" to download remote changes

Check repository binding:

- Verify the correct repository URL is configured - Ensure the branch name matches your working branch

Real-Time Status Updates

The runtime status badge refreshes automatically every 10 seconds. You can also:

• Manual refresh: Click the ↻ button on the badge
• View details: Click the badge to open the status popover
• Check sync history: Open Project Settings to see recent sync records

Using AI Tools for Diagnostics

AI agents can query runtime status using built-in tools:

get_project_sync_status

Returns current sync status, recent syncs, and repository binding info.

Use case: "What's the current sync status for this project?"

list_runtime_modes

Returns available runtime modes and current configuration.

Use case: "What runtime mode is this project using?"

Getting Help

If issues persist after following the troubleshooting steps:

Check the status page: Visit status.helm-ade.dev for service status

Review agent logs: helm-agent logs --tail 100

Contact support: support@helm-ade.dev with:

- Your project ID - Runtime mode (cloud/local) - Error messages - Agent logs (if using local mode)

Related Topics

• Runtime Hosting Modes — Configure runtime modes
• App Workspace Overview — Understanding the workspace