> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/planned-workouts-api/coercion-warnings.md).

# Coercion Warnings

> ⚠️ **Pre-Release / Under Construction**
>
> This page is currently **under active development** and is provided in a **pre-release state**.
>
> Content may be **incomplete, outdated, or inaccurate**, and details may changewithout notice as the implementation evolves.
>
> Please use this documentation for **early reference only**, and avoid relying on it for production-critical decisions until the page is marked as stable.

### What Are Coercion Warnings?

When a workout feature can't be fully represented on a provider's platform, Terra makes adjustments and returns **coercion warnings**. The workout is still created, but some details may differ from what you requested.

### Response Format

```json
{
  "status": "success",
  "planned_workout_id": 12345,
  "provider_workout_id": "garmin_abc123",
  "coercion_warnings": [
    {
      "path": "workout.sport",
      "message": "Unsupported sport type: yoga. Defaulting to OTHER."
    },
    {
      "path": "workout.step_blocks[1].steps[0].intensity_targets[1]",
      "message": "Secondary targets only supported for cycling and swimming. Target ignored."
    }
  ]
}
```

### Common Warning Scenarios

#### Missing Athlete Parameters

**Cause:** Workout uses percentage targets but required parameter wasn't provided.

```json
{
  "path": "threshold_heart_rate",
  "message": "heart_rate_threshold_percentage target requires threshold_heart_rate parameter. Using provider default."
}
```

**Fix:** Include the required parameter in your schedule request:

```json
POST /workouts/123/plan?user_id=X
{
  "planned_date": "2026-02-10",
  "threshold_heart_rate": 165
}
```

#### Unsupported Sport Type

**Cause:** Provider doesn't support the workout's sport.

```json
{
  "path": "workout.sport",
  "message": "Unsupported sport type: strength. Defaulting to OTHER."
}
```

**Impact:** Workout created but may display incorrectly on device.

#### Too Many Targets

**Cause:** Step has more targets than provider supports.

```json
{
  "path": "workout.step_blocks[0].steps[0].intensity_targets",
  "message": "Provider supports max 1 target per step. Using first target, ignoring 2 additional targets."
}
```

**Fix:** Prioritize your most important target as the first one.

#### Unsupported Target Type

**Cause:** Provider doesn't support the target type.

```json
{
  "path": "workout.step_blocks[0].steps[0].intensity_targets[0].target_type",
  "message": "cadence targets not supported. Target ignored."
}
```

#### Swimming Pool Length Missing

**Cause:** Swimming workout without pool length.

```json
{
  "path": "workout.pool_length_meters",
  "message": "Pool length not provided for swimming workout. Defaulting to 25 meters."
}
```

**Fix:** Set `pool_length_meters` in template or schedule request.

#### Unrecognized Exercise Name

**Cause:** Strength exercise name doesn't match Garmin's catalog.

```json
{
  "path": "workout.step_blocks[0].steps[0].strength.exercise_name",
  "message": "Exercise 'CUSTOM_EXERCISE' not found in Garmin catalog. Exercise name and category will be omitted."
}
```

**Impact:** Step still created, weight preserved, but exercise name/category not shown.

**Fix:** Use a recognized exercise name.

#### Block Completion Coercion

**Cause:** Provider doesn't support the block completion type.

```json
{
  "path": "workout.step_blocks[1].completion_condition",
  "message": "Time-based block completion not supported. Block will execute once."
}
```

#### Intensity Type Coercion

**Cause:** Provider doesn't support the intensity type.

```json
{
  "path": "workout.step_blocks[0].steps[0].intensity_type",
  "message": "RECOVERY intensity coerced to ACTIVE."
}
```

#### Sync Window (Zepp)

**Cause:** Workout scheduled outside the provider's sync window.

```json
{
  "path": "planned_date",
  "message": "workout date is outside Zepp's 7-day sync window; it will not appear on the device until it falls within range"
}
```

**Impact:** Workout is stored in Terra's database but won't appear on the device until it enters the 7-day window (today to today + 6 days). It will only be pushed to the device when a subsequent write or delete operation for that user triggers a window refresh — there is no automatic background sync.

#### Unsupported Sport (Zepp)

**Cause:** Sport type not natively supported by Zepp.

```json
{
  "path": "workout.sport",
  "message": "sport 'strength' not supported by Zepp, defaulting to 'RUNNING'. Supported sports: RUNNING, CYCLING, SWIMMING"
}
```

**Impact:** Workout is created but displays as a running workout on the device.

#### Cadence as Primary Target (Zepp)

**Cause:** Cadence provided as the only target without a primary target.

```json
{
  "path": "workout.step_blocks[0].steps[0].intensity_targets[0].target_type",
  "message": "cadence is only supported as a secondary target on Zepp; provide a primary target (pace, power, heart_rate) alongside it"
}
```

**Fix:** Add a primary target (heart rate, power, pace, or speed) and use cadence as a secondary target.

#### Swim Stroke Ignored (Zepp)

**Cause:** Zepp does not support stroke type metadata.

```json
{
  "path": "workout.step_blocks[0].steps[0].swimming.stroke_type",
  "message": "Zepp does not support stroke types, 'butterfly' will be ignored"
}
```

**Impact:** Swimming workout is created but stroke type is not displayed on the device.

### Handling Warnings in Your App

#### Log for Debugging

```python
response = create_planned_workout(workout_id, user_id, date, params)

if response.get('coercion_warnings'):
    for warning in response['coercion_warnings']:
        logger.warning(f"Workout coercion: {warning['path']} - {warning['message']}")
```

#### Show to Users (Optional)

For user-facing apps, you might surface relevant warnings:

```javascript
if (response.coercion_warnings?.length > 0) {
  showNotification({
    type: 'info',
    message: 'Some workout features were adjusted for your device.',
    details: response.coercion_warnings.map(w => w.message)
  });
}
```

#### Ignore If Acceptable

Many warnings are informational. If the workout still works for your use case, you can safely ignore them.

### Preventing Warnings

1. **Check Provider Compatibility** before building workouts
2. **Always provide athlete parameters** for percentage-based targets
3. **Use single targets** for maximum compatibility
4. **Use recognized exercise names** for strength training
5. **Set pool length** for swimming workouts
6. **Stick to common intensity types**: warmup, active, rest, cooldown