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

{
  "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.

{
  "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:

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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

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:

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