Why your ZWO file will not import to a Hammerhead Karoo

The rejection is all-or-nothing, and five step types is the whole list

Every step in a .ZWO file must be a warmup, cooldown, free ride, repeating interval, or steady state. MaxEffort is unsupported, and Ramp is listed as unsupported with coming soon beside it [Hammerhead Workout Import]. Anything else and Hammerhead rejects the file with an error rather than importing what it can.

The reason this bites so often is that the .ZWO format was designed for Zwift, where ramps and maximum-effort blocks are entirely ordinary. Most exporters target Zwift's tolerance rather than Hammerhead's, so a workout that opens with a ramped warmup or closes with an all-out sprint is a perfectly valid file that this particular importer will not take. Hammerhead states that unsupported interval types will be rejected and that you will see an error message to that effect [Hammerhead Workout Import].

That makes the diagnosis mechanical rather than mysterious. Open the file in a text editor and read the element names. If you find a MaxEffort or Ramp step anywhere in it, you have your answer, and it does not matter that the other fourteen steps are fine. The usual repair is to replace a ramp with a short staircase of steady-state blocks — three or four steps stepping up to the target approximate it closely enough for a warmup, and every one of them is a permitted type.

Treat the Ramp status as a moving target rather than a fixed rule. Hammerhead's own documentation marks it coming soon, which means a file that fails today may import later without anything on your side changing. Worth re-checking before rebuilding a library of workouts around the limitation. Durations, meanwhile, are always time in seconds in a .ZWO file, and distance-based workouts are converted to time-based ones on import.

The target rule, and one contradiction nobody can resolve

Every step must include at least one target: Power, a PowerHigh and PowerLow pair, Cadence, or a CadenceHigh and CadenceLow pair. Power takes preference when both are supplied, and zone-based power targets are not supported at all [Hammerhead Workout Import].

The zone rule is the sneaky one, because a zone-based workout is not malformed — it is just expressed in the wrong currency. A session written as ride zone 4 for ten minutes will not import; the same session written as a percentage of FTP will. If you author in a tool that thinks in zones, the export setting that switches to percentages is the fix, and it is usually one checkbox away from where you gave up. Those percentages then resolve against whichever FTP your Karoo holds, which is synced from a platform you nominate rather than set on the device [Hammerhead Training Metrics].

There is one contradiction in the published rules that we have not been able to resolve, and it is worth stating rather than papering over. Free ride is listed as a supported step type, and a free ride is self-paced by definition, yet the same document says every step must include at least one target. Both cannot hold literally. In our own exporter we treat the explicit support listing as the more specific rule and let free-ride steps through without a target — but that is an inference from two lines of documentation, not something we have tested against the live importer, and if your file consists mainly of free rides it is the first thing we would suspect.

The distinction that saves the most time is between rejected and ignored. Unsupported step types are rejected and take the file with them. Unsupported step fields are not: Hammerhead supports fields relating to cadence, power, duration, and repeat, and states that all others are ignored while the workout remains usable [Hammerhead Workout Import]. So a file that never appears and a file that appears with something missing are different diagnoses. The first is a step type. The second is a field you can stop hunting for.

When it is not a ZWO problem at all

Two more causes sit outside the .ZWO rules. The file may not be a workout, and the format may be incapable of carrying the targets you are trying to send. Only files with a .ZWO or .FIT extension are accepted in the first place [Hammerhead Workout Import].

The .FIT rules trip people who switch formats to escape the .ZWO ones. An activity or a route exported as .FIT is not a workout and is rejected, which is an easy mistake because all three share an extension and an analysis platform will happily offer you all three. The workout's sport type must be one of generic, cycling, e-bicycle, all, or invalid, and zone targets are rejected in .FIT just as they are in .ZWO [Hammerhead Workout Import]. There is also a quiet one here: an open-duration step with no target is silently ignored rather than rejected, so a file can import looking shorter than you built it.

The format decision that matters most is heart rate. A .FIT workout's steps can target speed, heart rate, cadence, or power — heart rate and power as absolute values or percentages, speed and cadence as absolute values — and heart rate does not appear among the .ZWO targets at all [Hammerhead Workout Import]. If you have been fighting a .ZWO export to carry heart-rate intervals, you have been fighting the wrong format, and no amount of editing will fix it. Note too that the Karoo does not support RPE-based workouts in any format [Hammerhead Karoo Workouts].

The rules follow the file rather than the route it took. Besides the Dashboard, you can share a workout file to the Karoo Companion App from your phone's share menu and have it turned into a workout on the device [Hammerhead Companion Sync] — convenient, but not a way around any of the constraints above. A step type the importer rejects is rejected whichever door the file came through.

We ended up encoding these rules in software rather than trusting an exporter to respect them. Every workout AdaptCycling pushes to a Karoo is checked against the permitted step types and the target rule before it leaves us, and a workout that fails is rejected with the offending step named — because Hammerhead rejects the file whole and gives no usable reason back, so a single bad step otherwise costs an athlete that entire day on the device with no explanation anywhere. That is the same principle our broader guide to training with a Hammerhead Karoo applies to the hardware: the device is faithful, and everything upstream of it has to earn that.

Quick answers

Sources cited in this guide

1. 01
   Hammerhead Workout Import. Dashboard - Importing ZWO & FIT based Workouts. Hammerhead Support.
2. 02
   Hammerhead Karoo Workouts. Karoo OS - Workouts. Hammerhead Support.
3. 03
   Hammerhead Training Metrics. Dashboard - Training Metrics. Hammerhead Support.
4. 04
   Hammerhead Companion Sync. Companion App - Uploads and Syncing. Hammerhead Support.

More inside Training with a Hammerhead Karoo

Other articles in this series

1. 01

   Karoo structured workouts without TrainingPeaks

   TrainingPeaks is not required, and Hammerhead's own docs are part of why people think it is. The free upload route and the providers that qualify.

   →
2. 02

   Training plan apps for the Hammerhead Karoo

   Hammerhead ships no training platform, so the app you connect is the plan. What TrainingPeaks, TrainerRoad, Intervals.icu and Xert each actually do.

   →
3. 03

   Intervals.icu to Karoo workout sync: how it works

   The official sync landed in January 2025 and is created from the Karoo itself. What syncs, what the importer rejects, and the format trap.

   →
4. 04

   Karoo workouts not syncing: how to find the real fault

   Check the Dashboard first — that one look halves the problem. The provider rules that block a push, the device half, and the failure that is not one.

   →
5. 05

   Karoo structured workouts without a power meter

   A heart-rate strap satisfies the Karoo's sensor requirement, but heart-rate targets exist only in FIT. What HR can target, and what it cannot.

   →