Skip to main content

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:
Third-party tools shown in some examples, such as DuckDB or plotly, are not 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).
An event name that matches no event of that season raises a different error. 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:
  1. Enable Debug Logging: See which CDN is failing.
  2. Reset Circuit Breaker: After several failures, the circuit breaker can be open.
  3. 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:
  1. Enable Logging: Read the reason in the warning.
  2. Report It: Open a GitHub issue with the warning text. It gives the reason for the failure.
A session that has no weather file at all logs 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:
  1. Keep the Cache: Leave caching enabled. The second load of a session reads the local cache.
  2. 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. Set ultra_cold_background_cache_fill to true in .tif1rc to write the cache in a background thread.

High Memory Usage

Problem: Analyzing an entire season consumes too much RAM. Solutions:
  1. Use Polars: It is significantly more memory-efficient than pandas.
  2. Categorical Types: On pandas, tif1 stores Driver, Team, Compound, and TrackStatus as category. 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. When tif1 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: Unexpected KeyError 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:
  1. Check the GitHub Issues.
  2. Run with logging.DEBUG and include the logs in the report.
  3. Provide a minimal reproducible example (MRE).

FAQ

Common questions.

Error Handling

Handle errors.

Installation

Setup issues.
Last modified on October 30, 2026