When you run a GTFS feed through a validator, errors are grouped into three categories:
This guide covers the errors and warnings you are most likely to encounter, with clear explanations of what causes each one and how to fix it.
What it means: Your ZIP archive is missing one of the mandatory GTFS files. The required files are: agency.txt, stops.txt, routes.txt, trips.txt, stop_times.txt, and either calendar.txt or calendar_dates.txt.
How to fix it: Check that all required files are present in the root of your ZIP (not inside a sub-folder). If a file is missing entirely, you need to create it. If it is inside a sub-folder, move it to the root level and re-zip.
What it means: Your ZIP contains a file that is not part of the GTFS specification (for example a .DS_Store file from a Mac, or a Thumbs.db from Windows).
How to fix it: Open your ZIP, delete any non-GTFS files, and re-zip. On a Mac, use Terminal to create the ZIP to avoid .DS_Store files being included automatically.
What it means: A mandatory column is absent from one of your files. For example, stops.txt must have stop_id, stop_name, stop_lat, and stop_lon.
How to fix it: Open the named file, check the header row (first row), and add any missing column headers. Then populate values for every row. The validator message will name both the file and the missing field.
What it means: A required field exists as a column but some rows have no value. For example, a stop is missing its stop_lat or a trip is missing its route_id.
How to fix it: The validator will tell you the file, field name, and row number. Open the file, go to that row, and fill in the missing value.
What it means: A value in one file references an ID that does not exist in another file. For example, a trip in trips.txt references a route_id that is not in routes.txt, or a stop time references a trip_id that is not in trips.txt.
How to fix it: Check that every ID referenced in one file exists in the corresponding file. This is often caused by a typo in an ID (e.g., "Route_1" vs "route_1" — GTFS IDs are case-sensitive). Copy-and-paste IDs between files rather than typing them to avoid this.
What it means: Two rows in the same file share the same primary key. For example, two stops with the same stop_id, or two routes with the same route_id.
How to fix it: Assign unique IDs to each record. If you accidentally copy-pasted a row, delete the duplicate. If you have two different stops that ended up with the same ID, rename one of them (and update all references to it in other files).
What it means: A row in stop_times.txt has an arrival time but no departure time, or vice versa. Both fields must be either both present or both absent.
How to fix it: For every stop time row, provide both arrival_time and departure_time. If a vehicle does not wait at a stop, set both values to the same time (e.g., 09:30:00 for both).
What it means: The shape_dist_traveled values in stop_times.txt are not strictly increasing along the trip.
How to fix it: Ensure each successive stop in a trip has a higher shape_dist_traveled value than the previous stop. This value represents cumulative distance from the start of the trip and must always increase.
What it means: Your service calendar extends more than a year into the future. This is flagged as a warning by most validators.
How to fix it: Set your end_date in calendar.txt to no more than 12 months from today. Plan to update your feed regularly to extend the calendar before it expires.
What it means: Your service calendar has no future dates — all defined service periods are in the past. This will cause your routes to disappear from Google Maps.
How to fix it: Update your calendar.txt end dates or add new entries in calendar_dates.txt that cover future service. Then re-publish your feed immediately. This is the most common reason transit agencies lose their Google Maps listing.
What it means: One of your stops is positioned far away from the route shape defined in shapes.txt. Google Maps uses shapes to draw the route line on the map.
How to fix it: Either correct the stop coordinates so the stop is on or near the route, or update your shape to pass through the correct location. A stop more than 100 metres from its shape will trigger this warning.
What it means: Similar to above, but specifically for the relationship between a stop used in a trip and that trip's shape.
How to fix it: Verify that every stop used in a trip is geographically consistent with where that trip travels. A common cause is using the same stop for both directions of a route when the stop positions differ slightly.
The best way to deal with GTFS errors is to prevent them from being created in the first place. AddTransit's built-in editor validates your data as you enter it, highlighting problems in real time before they make it into your feed file. You can also set up automatic feed hosting so your published feed stays current without manual intervention.
Agencies that switch from manual GTFS creation to AddTransit typically eliminate 90% of their validation errors on the first export.
