> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gymlive.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Guide

> Common issues and solutions for GymLive integrations

# Integration Troubleshooting Guide

This guide helps you resolve common issues with health aggregator and device integrations. Your coach uses this data to monitor your performance and workouts, so maintaining proper connections is important.

<Info>
  Based on integration best practices from [Terra's debugging guide](https://docs.tryterra.co/health-and-fitness-api/debugging-faq) and platform-specific requirements.
</Info>

## Quick Diagnostics

Before troubleshooting, verify:

<Steps>
  <Step title="Check Source App">
    Open the native app (Garmin Connect, Fitbit, etc.) and verify:

    * Recent data is visible
    * Device synced today
    * No error messages
  </Step>

  <Step title="Verify Cloud Sync">
    Log into the web dashboard:

    * [connect.garmin.com](https://connect.garmin.com)
    * [fitbit.com](https://www.fitbit.com)
    * [flow.polar.com](https://flow.polar.com)

    If data appears online, the issue is likely between the cloud and GymLive.
  </Step>

  <Step title="Check GymLive Status">
    In GymLive app:

    * Settings > Integrations
    * Verify "Connected" status
    * Note any error messages
    * Try pull-to-refresh
  </Step>
</Steps>

## Common Issues & Solutions

### 1. Wrong Account Connected

<Warning>
  This happens more often than you'd think! Many users have multiple accounts or family members' devices linked.
</Warning>

<Tabs>
  <Tab title="Fitbit">
    **Verify Fitbit User ID**:

    1. Open Fitbit app
    2. Tap profile picture (top left)
    3. Tap your display name
    4. Select "Personal"
    5. Scroll to bottom for User ID
    6. Compare with GymLive connected account

    **Fix**: Disconnect and reconnect with correct account
  </Tab>

  <Tab title="MyFitnessPal">
    **Check Username** (not email):

    1. In GymLive, note the connected username
    2. Navigate to: `myfitnesspal.com/food/diary/{username}`
    3. If page shows error, wrong username used

    **Common mistake**: Using email instead of username
  </Tab>

  <Tab title="Garmin">
    **Verify Account**:

    1. Log into connect.garmin.com
    2. Check profile name matches
    3. Verify recent activities present

    **Fix**: Re-authenticate with correct credentials
  </Tab>
</Tabs>

### 2. Platform-Specific Setup Issues

<AccordionGroup>
  <Accordion title="Garmin: No data after setup">
    **Issue**: Data shows in Garmin Connect but not GymLive

    **Solutions**:

    1. **Force sync in Garmin Connect**:
       * Mobile app: Pull down from top
       * Wait for sync circle to complete
    2. **Check web dashboard**:
       * Visit connect.garmin.com
       * If data missing there, device hasn't synced to cloud
       * If present, wait 1-2 minutes and refresh GymLive
    3. **Common delays**:
       * First sync: Up to 1 hour
       * Normal sync: 5-20 minutes
       * GPS activities: May take longer
  </Accordion>

  <Accordion title="Apple Health: Background sync not working">
    **Issue**: Data only syncs when app is open

    **Solutions**:

    1. **Battery settings**:
       * Settings > Battery
       * Turn OFF Low Power Mode
    2. **Background App Refresh**:
       * Settings > General > Background App Refresh
       * Ensure GymLive is ON
       * Ensure master toggle is ON
    3. **Force refresh** (requires iOS SDK 1.6.12+):
       * Contact support for manual backfill
       * If data comes through, background delivery issue confirmed
  </Accordion>

  <Accordion title="Google Fit: Long sync delays">
    **Issue**: 30-60 minute delays common

    **Solutions**:

    1. **Manual sync**:
       * Open Google Fit app
       * Pull down in journal tab
       * Wait for sync animation
    2. **Known limitations**:
       * Google API delays are normal
       * First sync may take up to 2 hours
       * Some data types have longer delays
    3. **Improve reliability**:
       * Keep Google Fit app active daily
       * Connect via Health Connect instead (Android 14+)
  </Accordion>
</AccordionGroup>

### 3. Health Connect (Android) Issues

<Warning>
  Health Connect is still evolving and has known platform bugs. These issues are outside GymLive's control.
</Warning>

**Common Problems**:

1. **Samsung Health not syncing to Health Connect**:
   * Must enable via Samsung Health > Settings > Health Connect
   * NOT via phone Settings > Apps
   * Tap "Sync now" and wait 2-3 minutes

2. **Apps can't write to Health Connect**:
   * Platform bug requiring Health Connect reinstall
   * Clear Health Connect cache
   * Re-grant all permissions

3. **Before going live** (developers):
   * Must apply for Google permissions
   * Use [this form](https://developer.android.com/health-and-fitness/guides/health_connect/publish)
   * Specify all data types needed

### 4. Data Not Syncing

Follow this diagnostic flow:

```mermaid theme={null}
graph TD
    A[No Data in GymLive] --> B{Data in Native App?}
    B -->|No| C[Sync Device to App]
    B -->|Yes| D{Data on Web?}
    D -->|No| E[Force Cloud Sync]
    D -->|Yes| F{Been 30+ min?}
    F -->|No| G[Wait & Refresh]
    F -->|Yes| H[Check Integration Status]
    H --> I[Reconnect if Needed]
```

### 5. Missing Historical Data

**Integration Limits**:

* Most platforms: 30 days historical max
* First sync: May miss older data
* Deleted data: Won't sync retroactively
* API restrictions: Some platforms limit historical access

**Platform-Specific**:

* **Fitbit**: 30 days on initial connection
* **Apple Health**: All data with proper permissions
* **Google Fit**: Limited historical windows
* **Garmin**: 30 days typical limit

### 6. Authentication Issues

<Tabs>
  <Tab title="Token Expired">
    **Symptoms**: Previously working integration stops

    **Fix**:

    1. Settings > Integrations
    2. Select affected platform
    3. Tap "Reconnect"
    4. Re-authenticate
    5. Grant all permissions again
  </Tab>

  <Tab title="Permission Changes">
    **Symptoms**: Partial data or missing metrics

    **Fix**:

    1. Platform may have updated permissions
    2. Disconnect integration
    3. Reconnect and review all permissions
    4. Ensure nothing was accidentally denied
  </Tab>
</Tabs>

## Live Device Connection Issues

### Bluetooth Troubleshooting

<AccordionGroup>
  <Accordion title="Device won't connect">
    1. **Enable broadcast mode** on device
    2. **Check Bluetooth**:
       * Turn off/on phone Bluetooth
       * Unpair device if previously paired
       * Restart both devices
    3. **Reduce interference**:
       * Move away from other Bluetooth devices
       * Avoid 2.4GHz WiFi routers
       * Test in different location
  </Accordion>

  <Accordion title="Constant disconnections">
    **Causes**:

    * Low battery (keep above 30%)
    * Distance too far (stay within 5m)
    * Phone sleeping (disable battery optimization)
    * Interference from other devices

    **Fix**: Address each cause systematically
  </Accordion>

  <Accordion title="Inaccurate heart rate">
    **Optical sensors** (wrist):

    * Tighten band (snug but comfortable)
    * Clean sensor window
    * Move higher on wrist
    * Allow 2-3 minute warm-up

    **Chest straps**:

    * Wet electrodes thoroughly
    * Check positioning (below pectorals)
    * Replace battery if >1 year old
    * Clean contacts monthly
  </Accordion>
</AccordionGroup>

### Watch App Issues

<Tabs>
  <Tab title="Wear OS">
    **App crashes**:

    1. Force stop: Settings > Apps > GymLive > Force Stop
    2. Clear cache (not data)
    3. Update Wear OS system
    4. Reinstall if persistent

    **Not syncing**:

    * Check phone app is running
    * Verify Bluetooth connected
    * Disable battery optimization
    * Sign out/in on both devices
  </Tab>

  <Tab title="Apple Watch">
    **Missing app**:

    1. iPhone Watch app > Available Apps
    2. Find GymLive and tap Install
    3. Restart both devices if not appearing
    4. Check storage space on watch

    **Heart rate gaps**:

    * Tighten watch band
    * Check for tattoo interference
    * Enable "Workout Power Saving" OFF
    * Consider chest strap for intervals
  </Tab>
</Tabs>

## Performance Optimization

### Battery Life Tips

<CardGroup cols={2}>
  <Card title="Devices" icon="battery-three-quarters">
    * Charge before workouts
    * Disable unused features
    * Update firmware regularly
    * Use power saving modes wisely
  </Card>

  <Card title="Apps" icon="mobile">
    * Allow unrestricted battery use
    * Keep apps updated
    * Close unused background apps
    * Enable airplane mode if not needed
  </Card>
</CardGroup>

### Sync Reliability

**Best Practices**:

1. **Daily routine**: Open apps in morning
2. **Post-workout**: Manual sync within 30 min
3. **Weekly**: Check integration status
4. **Monthly**: Review permissions

## When to Contact Support

Contact GymLive support if:

<Card title="Persistent Issues" icon="circle-exclamation">
  * Problem persists after all troubleshooting
  * Error messages you don't understand
  * Data loss or corruption
  * Integration shows "Error" status
  * Coach reports missing data
</Card>

**Before contacting support, gather**:

1. Screenshots of error messages
2. Integration status screens
3. Native app sync status
4. Device model and OS version
5. Time of last successful sync

## Prevention Tips

<Steps>
  <Step title="Regular Maintenance">
    * Update all apps monthly
    * Check integration status weekly
    * Clean device sensors
    * Replace batteries annually
  </Step>

  <Step title="Consistent Habits">
    * Sync devices same time daily
    * Charge devices overnight
    * Keep apps running in background
    * Don't force close apps
  </Step>

  <Step title="Monitor Changes">
    * Note app update changes
    * Review permission requests
    * Check for platform announcements
    * Update payment methods if needed
  </Step>
</Steps>

## Platform Status Pages

Check for known issues:

* [Apple System Status](https://www.apple.com/support/systemstatus/)
* [Google Workspace Status](https://www.google.com/appsstatus)
* [Garmin Connect Status](https://connect.garmin.com/status)
* [Fitbit Status](https://status.fitbit.com/)

<Note>
  Integration issues often resolve themselves within 24 hours due to temporary platform problems. If urgent, try alternative connection methods.
</Note>

## Related Resources

* Platform-specific integration guides in this documentation
* [Terra API Debugging Guide](https://docs.tryterra.co/health-and-fitness-api/debugging-faq)
* GymLive support: [support@gymlive.app](mailto:support@gymlive.app)