Troubleshooting

Common problems, the messages you will see, and what to do.

The application does not start

Message or symptom	What to do
macOS says the application cannot be opened or is from an unidentified developer	Test builds are not notarized. Use only builds from the project owner and report the message to them. Do not disable system protection.
FlappedEar Overlays is already running.	Switch to the open window. Only one editor can run at a time.
… cannot open its application data directory or … could not protect its recovery data	Check free disk space and the permissions of `~/Library/Application Support/FlappedEar/`.

Video problems

Message or symptom	What to do
Could not open video mentioning ffprobe, or ffprobe did not find a usable video stream	Install FFmpeg (Installing FFmpeg). Check that the file plays in QuickTime Player.
Video playback failed	The video cannot be decoded on this Mac. Convert it to H.264 or HEVC in MP4.
Chapter files open as separate videos or in the wrong order	Select all chapters of the recording together and check the order in the Video chapters dialog.
Overlay is in the wrong place on the picture	Widget positions are relative to the frame; check them in the WIDGET tab Geometry section.

Telemetry problems

Message or symptom	What to do
Choose an existing VBO or RaceChrono RCZ telemetry file.	Only `.vbo` and `.rcz` files are supported.
VBO has no [column names] section. / VBO has no [data] rows.	The file is not a complete VBO export. Export it again.
VBO has no recognised time column	The time column has a name the application does not know. Rename it to `time` in the `[column names]` section and open the file again. Row numbers are never used as time.
GPS coordinates and timing gates unavailable	The coordinate unit of this VBO is not known. See VBO files for the header line to add.
Timing gates ignored: this RaceChrono exporter version has not been validated.	Telemetry is usable, but no laps are derived from this file. Timing gates are read from RaceChrono Pro 10.2.4 VBO exports, the version that has been verified, and from other VBO files that declare `coordinate units` in the header. Other RaceChrono versions lose their gates.
Resumed sessions are not supported yet. / Multi-session or resumed archives are not supported	Share one uninterrupted session from RaceChrono, or use its VBO export.
A widget shows `—`	The channel has no value at this moment, or the widget is bound to a channel your file does not have. Check Source channel, the Live channels list in the DATA tab and the synchronization.
G-force dot never moves or is missing	Both lateral and longitudinal channels are needed. RCZ files have no calculated G; use a VBO export with calculated G, or select channels manually.

No laps found

Lap timing comes from the timing gate stored in the telemetry file. The status shows the reason:

Status	Meaning and fix
No Start gate in telemetry	The recording contains no start/finish line. In RaceChrono, record with a track that has a start/finish line, then export again. An RCZ on a library track needs at least one complete lap recorded by RaceChrono for the line to be rebuilt.
Multiple Start gates in telemetry	Exactly one start gate is required.
Start gate geometry is invalid	The stored line could not be used.
No usable GPS for lap timing	GPS is missing or its unit is unknown (see above).
No Start-line passages detected / One Start-line passage detected; no complete lap	The car did not cross the line twice in the same direction during the recording. Passing close to the line without going over it, or going over it more than 5 m beyond either end, does not count.

A recording without crossings has one UNKNOWN section and no laps, and a run whose layout or gate is unresolved is left out when the Export dialog looks for the day's best lap.

Synchronization problems

See the message table in Automatic synchronization. If automatic synchronization finds a wrong match (for example because several laps look alike), click Ignore and set the offset manually.

Export problems

Message	What to do
FFmpeg with an HEVC encoder is required… / FFprobe is required…	Install FFmpeg with Homebrew; see Installing FFmpeg.
No requested HEVC encoder is available in this FFmpeg build. / Encoder … cannot encode …	Install an FFmpeg build with VideoToolbox or libx265, or choose a smaller resolution.
Export stops early with a filter or composition error	The FFmpeg version lacks a required filter. Update FFmpeg.
Open a video and telemetry, then choose an output file.	Load both sources and pick an output file.
Export range must use valid inclusive SMPTE IN and OUT timecodes…	Use `HH:MM:SS:FF` with colons, with IN before OUT and both inside the video.
Export format is invalid…	Choose one of the offered sizes and rates, and a bitrate from 0.5 to 500 Mbps.
Not enough free space for export…	Free space on the destination and on the system disk (temporary files), or choose a lower bitrate or shorter range.
Export output cannot be the input video. / …collides with a source or temporary file.	Choose a new file name.
Export target must be a regular file, not a symbolic link… / Export destination directory does not exist.	Choose a normal file in an existing folder.
Export finished, but the destination file changed while the export was running.	Another program changed the target. Your newer file was protected; export again to a new name.
FFmpeg encoder appears stalled (no progress for five minutes).	Close other heavy applications, try again, and send the export log if it repeats.
…failed validation	The result did not pass the final checks and was not saved. Send the export log.
HDR/Log, rotation, non-square pixel or chapter messages	See Sources that cannot be exported.

Template problems

If a red error appears under Layout template, the custom template store could not be read. Move ~/Library/Preferences/FlappedEar/FlappedEar Overlays/layout-templates.json to another folder, or restore a good copy, then click Reload templates under the message. Restarting the application has the same effect. Built-in templates are always available. You can then import templates you exported earlier.

A red error under My widgets means the same for saved widgets: quit, move widget-library.json from the same folder aside, start again, and import any .fetwidget files you exported.

Reporting a problem

Include:

what you did and what you expected;
the exact message text;
for export problems, the export log from ~/Library/Application Support/FlappedEar/FlappedEar Overlays/exports/, or the text from Details → Very verbose → Copy all;
the output of ffmpeg -version and your macOS version;
the application log flappedear.log from ~/Library/Application Support/FlappedEar/FlappedEar Overlays/.

Do not attach private recordings publicly. Report issues at GitHub Issues.