Troubleshooting

FastF1 loads no laps

session.load() logs “Failed to load timing data”, and session.laps then raises DataNotLoadedError. Since about 15 October 2026, F1’s archive refuses downloads without an F1 TV Access subscription (FastF1 #978). Your options:

• Use a FastF1 cache filled before mid-October; it still loads offline (fastf1.Cache.offline_mode(True) stops FastF1 trying the network).
• Install the pre-release with sign-in support, fastf1==3.9.0a0, and follow its authentication docs. lapbox’s tests pass with it.

This is FastF1’s data access, not lapbox: lapbox analyses whatever FastF1 loaded.

compare says matched is False

The two laps couldn’t be put on the same points of track: their speed traces still differ by more than 15 km/h RMS after alignment. Look at Comparison.frozen_a and Comparison.frozen_b — on 2026 qualifying, a lap with frozen car data was behind every refusal measured. Then:

• Don’t show the time gap, speed delta, corner speeds, minisectors or segments.
• Each lap’s own trace and numbers are still fine.
• Try another lap of the same driver: pick_fastest() isn’t the only lap with representative data.

See When a pair can’t be compared.

A function returned None or an empty table

That is a refusal, not a bug. The usual reasons:

• clean_air_split: fewer than three laps in clean air or in traffic — a driver who led throughout or never got clear.
• driver_consistency: fewer than three representative laps.
• ideal_lap: a sector never timed on a clean lap, or the sum of best sectors slower than the fastest lap.
• detect_frozen_stretches empty: nothing froze — or the telemetry has no clock (Time) or lacks one of Speed, RPM, nGear, Throttle, so nothing could be judged.
• detect_runs empty: no driver, lap-number or lap-time column (a warning is logged).
• A driver missing from true_pace_ranking or a stint from stint_degradation: fewer than three representative laps.

import lapbox.plot raises ImportError

Plotly isn’t installed. The charts are an optional extra:

pip install "lapbox[plot]"

KeyError: No degradation model for compound

TyreDegradationModel didn’t fit that compound: it had fewer than min_laps (5) laps within 107 % of their drivers’ best, or only one tyre age. Rain tyres in a mixed race usually drop out this way. Check model.compounds for what was fitted.

The tyre got quicker with age

A negative degradation rate is common on low-wear circuits: the slope is small next to the noise, and it also carries track evolution and the fuel assumption. Read it with its laps and r2, and clamp it before using it to plan. See How far to trust a rate.

The corner count doesn’t match the circuit map

detect_corners finds places where the car slows down, so flat-out kinks — which the official numbering includes — don’t count. It finds the same corners on every lap of a circuit, which is what comparing laps needs. Lower prominence to find more.

My numbers changed after upgrading

Until 1.0 a release can change a calculation when a measurement shows it should — for example, 0.1.0.dev14 dropped lap 1 from true_pace_ranking. The changelog lists every such change and how much it moved. Pin lapbox==0.1.0 where results must stay put.