Known issues

Nothing here matches? Email support@relay-agent.app, reply within 48 hours. If you can, attach the app's "Sync log", which holds no health values.

The workout doesn't show up on the Watch

Since iOS 18.2, WorkoutKit, the Apple service that sends workouts to the Watch, sometimes leaves a workout scheduled on the iPhone without ever showing it on the Watch.

1. Open Relay. The app schedules workouts while it is in the foreground, which avoids the defect most of the time. If a workout arrives while the app is in the background, it sends you a notification asking you to open it.
2. Otherwise, reschedule everything. In the app, Settings, "Reschedule everything on the watch". The app removes and resends all workouts: this is the fix Apple recommends.

The Watch only shows a workout on its planned day, in the Workout app. A workout planned for tomorrow is not there yet today.

On-demand refresh doesn't respond

Your agent asks for a sync, the iPhone doesn't answer within 25 seconds and relay-agent rafraichir returns 504. Known causes:

• The iPhone is locked. iOS encrypts Health data while the iPhone is locked: no app can read it. The wake-up works as soon as the iPhone is unlocked.
• Personal Hotspot is on. Silent notifications don't arrive in that case.
• The app was swiped away. iOS no longer relaunches it in the background. Open it once.
• Apple does not guarantee delivery of silent notifications; iOS sometimes delays them.

Two normal answers: if the last sync is less than two minutes old, the relay doesn't wake the iPhone and returns the data in place. Beyond 6 wake-ups in an hour, it answers 429.

Some data arrives late

iOS wakes Relay as soon as a meal, a weigh-in, a night of sleep, a workout, an HRV or resting heart rate reading arrives. For steps, energy, exercise minutes and water, Apple limits the wake-up to once an hour at best. On-demand refresh closes the gap.

"Subscription required"

The relay answers 402 and relay-agent exits with code 4 when your agent plans a workout or asks for a refresh without an active subscription. Subscribe in the app, or use "Restore a purchase" if you already have. After purchase, the app passes the subscription to the relay at its next sync.

"Unknown or expired session" while pairing

A relay-agent relier session lasts ten minutes. Run the command again and enter the new session. If the six-digit codes differ between the app and the agent, answer "No, they differ" and start over: someone may have stepped in between.

My agent has no screen to compare the code

Use the pairing phrase: in the app, Settings, "Pairing phrase (backup)". Copy it to ~/.config/relay/phrase, readable by you only (mode 600), or to the RELAY_PHRASE variable.