Skip to main content
tif1 uses a structured exception hierarchy for graceful error handling. The tif1 exceptions inherit from TIF1Error, so one except TIF1Error clause catches them. EventNotFoundError and its subclass EventNotInSeasonError are not part of this tree. They are ValueError subclasses, raised when an event name does not resolve to an event of the season.

Exception Hierarchy

Common Exceptions

DataNotFoundError

Raised when requested data does not exist in the archive.
Common causes:
  • A lap number or driver code that is not in the session
  • The session has not started yet
  • Data not yet available in archive
An unknown event name does not raise DataNotFoundError. It raises EventNotFoundError, a ValueError (see EventNotFoundError). An unknown session name raises ValueError.
Solution:

DriverNotFoundError

Raised when code accesses a driver that does not exist in the session. It is a DataNotFoundError and also a ValueError, the exception that fastf1 raises for an unknown driver.
Solution:

EventNotFoundError

Raised by get_session and get_event_by_name when an event name matches no event of the season. EventNotFoundError is a ValueError, not a TIF1Error, so except TIF1Error does not catch it. tif1 resolves an event name in three steps: the exact name, then a table of circuit, city, and country aliases, then fuzzy matching. A typo such as "Monacco" resolves to the Monaco Grand Prix and logs a Correcting user input warning. A fuzzy match needs a score of at least 70 out of 100. A name below that score, such as "Moon GP", raises EventNotFoundError. An alias for an event that is not on that season’s calendar raises EventNotInSeasonError, a subclass of EventNotFoundError. An example is "Suzuka" in 2021.
To catch every tif1 error, including an unknown event name, catch both base classes:

NetworkError

Raised when all CDN sources fail or time out. While the circuit breaker is open, loads also fail with NetworkError. CircuitBreakerOpenError, the breaker’s own refusal, is a NetworkError subclass. By default, the circuit breaker opens after 5 network failures in a row (circuit_breaker_threshold). It then refuses requests for 60 seconds (circuit_breaker_timeout). After that time, requests go through again, and the first success closes the breaker. A missing file (404), a refused file (403), or an InvalidDataError does not count as a failure.
Solutions:
  • Check internet connection
  • Verify the CDN sources (jsDelivr, Hugging Face, StaticDelivr) are accessible
  • Reset circuit breaker if needed
  • Re-enable CDN sources with tif1.get_cdn_manager().reset(). A source that fails 3 times in a row stays off until this reset.
  • Enable debug logging to see which CDN failed

InvalidDataError

Raised when a fetched payload is not a JSON object, or fails the optional payload validation. The validate_data, validate_lap_times, and validate_telemetry options are off by default. tif1 does not retry an invalid payload.

CacheError

tif1 exports CacheError but does not raise it. When SQLite cannot open or write the cache database, tif1 logs a warning. It then continues without the SQLite cache, so loads are slower but do not fail.

SessionNotLoadedError

tif1 exports SessionNotLoadedError but does not raise it. Session data properties such as session.laps load their data on first access. Like every TIF1Error, it accepts keyword arguments as error context.

Error handling patterns

Graceful Degradation

Handle errors without stopping the analysis.

Retry Logic

tif1 already sends each request up to max_retries times (default 3), with exponential backoff between tries. A value of 0 makes one attempt, the same as 1. The first load of a session that is not in the cache makes one attempt per CDN source (ultra_cold_skip_retries). tif1 does not retry a 403, a 404, or an InvalidDataError, because a new attempt gets the same answer. Add an application-level retry for network failures that last longer than the built-in retries.

Batch Processing

Handle errors when processing multiple sessions.

Context Managers

Use context managers for resource cleanup.

Debugging Errors

Enable debug logging

See detailed information about the operations in progress.

Inspect error context

Every TIF1Error carries a context dict with the keyword arguments it was raised with.

Check circuit breaker

Monitor network health.

Best Practices

1

Validate Input

Check data availability before processing.
2

Use Specific Exceptions

Catch specific exceptions rather than broad Exception.
3

Log Errors

Always log errors for debugging.
4

Fail Fast

Do not continue processing when critical data is missing.

Production Patterns

Health Checks

Monitor tif1 health in production.

Monitoring

Track errors and performance.

Summary

Proper error handling keeps tif1 applications stable and maintainable. Always use specific exceptions, validate input, and add retry logic for production use.

Exceptions API

Exception reference

Troubleshooting

Common issues

Best Practices

Recommended patterns
Last modified on October 30, 2026