Coercion Warnings

What Are Coercion Warnings?

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

Warnings also travel the other way. When GET /plannedWorkouts returns a workout the athlete created on the provider's side, Terra converts that workout into the same workout body it uses everywhere else, and anything it could not carry across arrives as a warning on that item.

Response Format

{
  "status": "success",
  "planned_workout_id": "2048",
  "provider_workout_id": "88112233/44556677",
  "warnings": [
    {
      "path": "workout.sport",
      "message": "sport 'rowing' not directly supported by Garmin, using GENERIC"
    },
    {
      "path": "workout.step_blocks[1].steps[0].intensity_targets[1].target_type",
      "message": "Garmin uses heart rate percentage of max HR, not threshold HR. The percentage values will be interpreted as % of max HR."
    }
  ]
}

Read warnings. It is always present and is an empty array when nothing was adjusted. coercion_warnings carries the same list, is deprecated, and on GET /plannedWorkouts is a JSON string rather than an array.

Warnings on Listed Workouts

GET /plannedWorkouts returns workouts created through Terra and workouts the athlete created on the provider's side (is_external: true). Both kinds carry the same workout body and the same warnings array.

On a Terra-created workout, warnings says what was lost pushing your template to the provider. On a provider-created workout, it says what was lost reading the provider's workout back into a Terra workout body. For example, Intervals.icu nests a repeat group only when the workout text uses its documented syntax, a blank line before and after the 3x line. Written any other way, the steps come back flat.

Two warning paths tell you where a missing body came from:

Warning path	What it means
workout (with workout: null)	Terra could not load the stored body of a workout you created.
step_blocks (with step_blocks: [])	The provider returned the workout, but its step file could not be fetched. Name, sport and estimates are there, the steps are not.

Provider-created workouts are listed for Garmin, Wahoo, Suunto, TrainingPeaks and Intervals.icu. Intervals.icu is read only: you can list its workouts but not push to it, so its warnings always come from reading.

Common Warning Scenarios

Missing Athlete Parameters

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

{
  "path": "workout.step_blocks[0].steps[0].intensity_targets[0]",
  "message": "HR threshold percentage target requires a threshold HR baseline. Using default threshold HR of 170 bpm. Provide threshold_heart_rate for accurate targets."
}

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": "sport 'rowing' not directly supported by Garmin, using GENERIC"
}

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": "Zepp supports one primary target and one optional cadence secondary target, ignoring 2 extra target(s)"
}

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": "Target type 'cadence' not supported by Garmin for this sport. Using OPEN instead."
}

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": "Could not determine category for exercise name 'CUSTOM_EXERCISE', dropping exercise name/category but keeping weight data"
}

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

Estimates Ignored (TrainingPeaks)

Cause: The workout supplies estimated_tss, estimated_intensity_factor or estimated_duration_seconds, and at least one step target is not RPE.

{
  "path": "workout.estimated_tss",
  "message": "TrainingPeaks derives this from the step targets when any target is not RPE; the supplied value is ignored"
}

Impact: Terra forwards estimated_tss, estimated_intensity_factor, estimated_distance_meters and estimated_calories to TrainingPeaks when you plan a workout and when you reschedule it. TrainingPeaks recalculates TSS, intensity factor and duration from the athlete's own thresholds whenever a step uses anything other than an RPE target. You get one warning per value you supplied. Distance and calories are unaffected.

Fix: Use RPE targets throughout if your own TSS and intensity factor need to stick. Otherwise treat TrainingPeaks' numbers as the source of truth.

estimated_tss must be between 0 and 9999 and estimated_intensity_factor between 0 and 5. Outside those ranges the template is rejected with a 400 when you create it, not coerced.

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: The planned workout is saved and returned by the API, but it won't appear on the device until it enters the 7-day window (today to today + 6 days). It is pushed the next time you create, reschedule or delete a workout for that user, which refreshes the window. Nothing is pushed in the background.

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, LAP_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)

for warning in response.get('warnings', []):
    logger.warning("Workout coercion: %s - %s", warning['path'], warning['message'])

Show to Users (Optional)

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

if (response.warnings?.length > 0) {
  showNotification({
    type: 'info',
    message: 'Some workout features were adjusted for your device.',
    details: response.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