Installation Issues
Missing Dependency After a Manual Uninstall
Error:ModuleNotFoundError: No module named 'polars' (or pyarrow or timple; or zstandard on Python 3.11 to 3.13)
Solution:
tif1 declares these as dependencies, so a clean install never hits this error. On Python 3.14 and later zstandard is not installed because the standard library provides zstd. Reinstall tif1 to restore the others:
tif1 dependencies. Install them separately when an example needs them.
Polars Version Conflict
Error:pip reports a conflict such as tif1 requires polars<3,>=2.0.0, or user code raises polars.exceptions.AttributeRemovedError after an upgrade.
Solution:
tif1 requires polars 2.x. Upgrade polars, then check the version:
AttributeRemovedError and ArgumentRemovedError come from APIs that polars deprecated in 1.x and removed in 2.0. The error message names the replacement. See Polars 2 notes for the changes that affect code written on tif1 frames.
Data Access Issues
DataNotFoundError
Error:DataNotFoundError: Data not found: year=2025, event='Abu Dhabi Grand Prix', session='Practice 1'
Causes:
- Data not yet available in the archive.
- The session did not take place.
- A driver code or lap number that does not exist (
DriverNotFoundError,LapNotFoundError).
get_session raises EventNotFoundError, a ValueError subclass, with the message No event matching '<name>' in <year>. An event that is not on the calendar of that season, for example "Suzuka" in 2021, raises EventNotInSeasonError, a subclass of EventNotFoundError.
tif1 resolves circuit, city, and country names such as "Spa" to the correct event. A misspelled event name such as "Monacco" does not raise: tif1 corrects it to the closest event name and logs a warning. A name that resembles no event, such as "Paris", raises EventNotFoundError. A session name that does not exist raises ValueError and lists the available names.
Solutions:
NetworkError
Error:NetworkError: Network request failed: url='...'
Solutions:
- Enable Debug Logging: See which CDN is failing.
- Reset Circuit Breaker: After several failures, the circuit breaker can be open.
- Check CDN Status: The primary CDN is jsDelivr, with Hugging Face buckets and StaticDelivr as fallbacks. Make sure that the network does not block them.
Empty Weather or Race Control Table
Symptom:session.weather or session.race_control_messages returns an empty DataFrame. The log shows Failed to load weather for ... or Failed to load race control messages for ....
Cause: These tables are optional. A download failure (NetworkError), a validation failure, or a failed dtype conversion makes tif1 log a warning. It returns an empty DataFrame instead of raising. Laps and telemetry are not affected.
Solutions:
- Enable Logging: Read the reason in the warning.
- Report It: Open a GitHub issue with the warning text. It gives the reason for the failure.
No weather in session at INFO level and also returns an empty DataFrame. See Empty weather or race control tables.
Performance Issues
Slow Cold Start
Problem: The first load of a session takes several seconds. Solutions:- Keep the Cache: Leave caching enabled. The second load of a session reads the local cache.
- Ultra Cold Start: The ultra cold start path is on by default (
ultra_cold_start). It skips cache reads and validation for a session that is not cached yet. Setultra_cold_background_cache_filltotruein.tif1rcto write the cache in a background thread.
High Memory Usage
Problem: Analyzing an entire season consumes too much RAM. Solutions:- Use Polars: It is significantly more memory-efficient than pandas.
- Categorical Types: On pandas,
tif1storesDriver,Team,Compound, andTrackStatusascategory. Make sure that the code does not cast these columns back to strings.
Cache Issues
Cache Permissions
Symptom: The cache does not fill, so every run downloads the data again. Whentif1 cannot open the database, the log shows SQLite cache unavailable: ....
Solution:
Ensure tif1 can write to its cache directory and to cache.sqlite in it. The default is Windows %LOCALAPPDATA%/Temp/tif1, macOS ~/Library/Caches/tif1, or Linux/other POSIX ~/.cache/tif1 (falling back to ~/.tif1). tif1 sets 0o700 permissions on the directory when it opens the cache.
Corrupted Cache
Problem: UnexpectedKeyError or InvalidDataError after a successful load.
Solution:
Wipe the local cache and re-download the data.
API & Schema Issues
Column Name KeyError
Error:KeyError: 'time' or KeyError: 'speed'
Solution:
tif1 uses the fastf1 column names, which are mostly PascalCase. Use LapTime instead of time, and Speed instead of speed. The laps table has no Speed column: its speed-trap columns are SpeedI1, SpeedI2, SpeedFL, and SpeedST.
TypeError When Comparing LapTime
Error:TypeError from laps[laps["LapTime"] < 90] on pandas. On polars, LapTime is Duration("ns"), and laps["LapTime"] < 90 raises NotImplementedError (a Duration Series cannot compare with an integer). Inside an expression, laps.filter(pl.col("LapTime") < 90) raises nothing: polars reads 90 as 90 nanoseconds, so the filter silently returns no rows.
Solution:
LapTime is timedelta64[ns] on pandas and Duration on polars. Compare LapTimeSeconds, which is a float on both backends, or compare LapTime with a duration:
On polars, select rows with
filter. See Column types by backend.
Getting Help
If the problem persists:- Check the GitHub Issues.
- Run with
logging.DEBUGand include the logs in the report. - Provide a minimal reproducible example (MRE).
Related Pages
FAQ
Common questions.
Error Handling
Handle errors.
Installation
Setup issues.