feat: Add ignore-missing-files cli option to avoid crashing at startup

[andrewlaguna824]

Add --ignore-missing-files flag to prevent crash on startup

Problem

When deploying tileserver-gl, the application crashes during startup if any configured mbtiles/pmtiles files don't exist.
This currently causes an issue in our deployments where large files, such as mbtiles, are loaded separately.

Concretely, the issue is that since files are required on startup, our k8s pod running tileserver-gl will crash loop until
the configured files are available in storage. However, since the pod is crash looping, we are unable to transfer the files
to storage.

Right now, we have a workaround to either load tileserver-gl with an empty config at first or to hack the pod startup into an
infinite sleep loop while we load the tiles into storage. This makes deployments manual and configuration management cumbersome.

Solution

This PR adds a new --ignore-missing-files CLI flag that allows tileserver-gl to start successfully even when some configured data sources are missing. When enabled:

• Missing data sources are skipped during initialization and warning are logged
• Styles with missing data sources are skipped
• Requests to skipped data sources and styles return 404

The default behavior remains unchanged to maintain backward compatibility.

Usage

# Start with the flag to ignore missing files
tileserver-gl --config config.json --ignore-missing-files

Testing

With Flag and Missing MBTiles

Log Warnings at Startup

tileserver-gl-1  | Starting tileserver-gl v5.5.0-pre.9
tileserver-gl-1  | Using specified config file from config.json
tileserver-gl-1  | Starting server
tileserver-gl-1  | Listening at http://[::]:8080/
tileserver-gl-1  | WARN: Style 'default-bad' references 1 missing data source(s): [openmaptiles] - not adding style
tileserver-gl-1  | WARN: Data source 'vector-global-bad' file not found: "/data/data/zurich-bad.mbtiles" - skipping
tileserver-gl-1  | Startup complete

Problematic Style Not in Repository

user ~/dev/tileserver-gl [andrewlaguna824/ignore-missing-files] $ curl http://localhost:8080/styles.json | jq
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   107  100   107    0     0  17569      0 --:--:-- --:--:-- --:--:-- 17833
[
  {
    "version": 8,
    "name": "OSM Liberty",
    "id": "default",
    "url": "http://localhost:8080/styles/default/style.json"
  }
]

Problematic Style Returns 404 for Rendered Tile

user ~/dev/tileserver-gl [andrewlaguna824/ignore-missing-files] $ curl -v http://localhost:8080/styles/default-bad/0/0/0.png
* Host localhost:8080 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:8080...
* Connected to localhost (::1) port 8080
> GET /styles/default-bad/0/0/0.png HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 404 Not Found
< Access-Control-Allow-Origin: *
< Content-Type: text/plain; charset=utf-8
< Content-Length: 9
< ETag: W/"9-0gXL1ngzMqISxa6S1zx3F4wtLyg"
< Date: Mon, 22 Dec 2025 21:31:19 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
* Connection #0 to host localhost left intact
Not Found%

Problematic Datasource Returns 404

user ~/dev/tileserver-gl [andrewlaguna824/ignore-missing-files] $ curl -v http://localhost:8080/data/zurich-bad.json
* Host localhost:8080 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:8080...
* Connected to localhost (::1) port 8080
> GET /data/zurich-bad.json HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 404 Not Found
< Access-Control-Allow-Origin: *
< Content-Type: text/plain; charset=utf-8
< Content-Length: 9
< ETag: W/"9-0gXL1ngzMqISxa6S1zx3F4wtLyg"
< Date: Mon, 22 Dec 2025 15:20:00 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
Not Found%

Without Flag and Missing MBTiles (original behavior)

tileserver-gl-1  | Starting tileserver-gl v5.5.0-pre.9
tileserver-gl-1  | Using specified config file from config.json
tileserver-gl-1  | Starting server
tileserver-gl-1  | Listening at http://[::]:8080/
tileserver-gl-1  | Unhandled Promise Rejection at: Promise {
tileserver-gl-1  |   <rejected> Error: ENOENT: no such file or directory, stat '/data/data/zurich-bad.mbtiles'
tileserver-gl-1  |       at async Object.stat (node:internal/fs/promises:1039:18)
tileserver-gl-1  |       at async Object.add (file:///usr/src/app/src/serve_rendered.js:1658:34) {
tileserver-gl-1  |     errno: -2,
tileserver-gl-1  |     code: 'ENOENT',
tileserver-gl-1  |     syscall: 'stat',
tileserver-gl-1  |     path: '/data/data/zurich-bad.mbtiles'
tileserver-gl-1  |   }
tileserver-gl-1  | }
tileserver-gl-1  | Reason: Error: ENOENT: no such file or directory, stat '/data/data/zurich-bad.mbtiles'
tileserver-gl-1  |     at async Object.stat (node:internal/fs/promises:1039:18)
tileserver-gl-1  |     at async Object.add (file:///usr/src/app/src/serve_rendered.js:1658:34) {
tileserver-gl-1  |   errno: -2,
tileserver-gl-1  |   code: 'ENOENT',
tileserver-gl-1  |   syscall: 'stat',
tileserver-gl-1  |   path: '/data/data/zurich-bad.mbtiles'
tileserver-gl-1  | }
tileserver-gl-1  | Not valid input file: "/data/data/zurich-bad.mbtiles"
tileserver-gl-1 exited with code 1

[okimiko]

I had the same issue with some styles using optional data files and solved it with a script, which generated a valid config/stubbed files and reloaded the tileserver on demand.

I like this as I could drop some of the stubbed stuff 👍

[okimiko]

I tested these changes and everything works as expected, but only if the data source is configured: If there is a unconfigured data source in the style, we will have the previous behaviour.

This fixed the issue for me: okimiko@cc9cff8

[andrewlaguna824]

Thanks! Made the suggested changes and tested it on my end.

[okimiko]

Fine for me now 👍