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.- 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.DriverNotFoundError
Raised when code accesses a driver that does not exist in the session. It is aDataNotFoundError and also a ValueError, the exception that fastf1 raises for an unknown driver.
EventNotFoundError
Raised byget_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.
NetworkError
Raised when all CDN sources fail or time out. While the circuit breaker is open, loads also fail withNetworkError. 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.
- 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. Thevalidate_data, validate_lap_times, and validate_telemetry options are off by default. tif1 does not retry an invalid payload.
CacheError
tif1 exportsCacheError 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 exportsSessionNotLoadedError 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 tomax_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
EveryTIF1Error 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.Related Pages
Exceptions API
Exception reference
Troubleshooting
Common issues
Best Practices
Recommended patterns