fix: ensure tiles still load when failing to generate cache metadata (#2125)

Author: JaffaKetchup

CHANGELOG.md

@@ -4,6 +4,17 @@ Please consider [donating](https://github.com/sponsors/fleaflet) or [contributin
 
 This CHANGELOG does not include every commit and/or PR - it is a hand picked selection of the ones that have an effect on you. For a full list of changes, please check the GitHub repository releases/tags.
 
+## [8.2.1] - 2025/07/11
+
+Contains the following user-affecting changes:
+
+- Ensure tiles still load when failing to cache them due to HTTP spec non-compliance - [#2125](https://github.com/fleaflet/flutter_map/pull/2125) for [#2124](https://github.com/fleaflet/flutter_map/issues/2124)
+- Log informational warnings to console when a tile fails to cache due to HTTP spec non-compliance or a shortage of information to calculate an accurate freshness age - [#2125](https://github.com/fleaflet/flutter_map/pull/2125) for [#2124](https://github.com/fleaflet/flutter_map/issues/2124)
+
+Many thanks to these contributors (in no particular order):
+
+- ... and all the maintainers
+
 ## [8.2.0] - 2025/07/10
 
 Contains the following user-affecting changes:

example/pubspec.lock

@@ -116,7 +116,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "8.2.0"
+    version: "8.2.1"
   flutter_test:
     dependency: "direct dev"
     description: flutter

example/pubspec.yaml

@@ -1,7 +1,7 @@
 name: flutter_map_example
 description: Example application for 'flutter_map' package
 publish_to: "none"
-version: 8.2.0
+version: 8.2.1
 
 environment:
   sdk: ">=3.6.0 <4.0.0"

lib/src/layer/tile_layer/tile_provider/network/caching/tile_metadata.dart

@@ -1,8 +1,9 @@
 import 'dart:io' show HttpHeaders, HttpDate; // web safe!
 import 'dart:math';
 
+import 'package:flutter/foundation.dart';
 import 'package:flutter_map/flutter_map.dart';
-import 'package:meta/meta.dart';
+import 'package:logger/logger.dart';
 
 /// Metadata about a tile cached with a [MapCachingProvider]
 ///
@@ -24,11 +25,27 @@ class CachedMapTileMetadata {
   /// Create new metadata based off an HTTP response's headers
   ///
   /// Where a response does not include enough information to calculate the
-  /// freshness age, [fallbackFreshnessAge] is used.
+  /// freshness age, [fallbackFreshnessAge] is used. This will emit a console
+  /// log in debug mode if [warnOnFallbackUsage] is is set.
+  ///
+  /// This may throw if the required headers were in an unexpected format.
   factory CachedMapTileMetadata.fromHttpHeaders(
     Map<String, String> headers, {
+    Uri? warnOnFallbackUsage,
     Duration fallbackFreshnessAge = const Duration(days: 7),
   }) {
+    void warnFallbackUsage() {
+      if (kDebugMode && warnOnFallbackUsage != null) {
+        Logger(printer: SimplePrinter()).w(
+          '[flutter_map cache] Using fallback freshness age '
+          '($fallbackFreshnessAge) for ${warnOnFallbackUsage.path}\n'
+          '\tThis indicates the tile server did not send enough '
+          'information to calculate a freshness age. Optionally override '
+          "in the caching provider's config.",
+        );
+      }
+    }
+
     // There is no guarantee that this meets the HTTP specification - however,
     // it was designed with it in mind
     DateTime calculateStaleAt() {
@@ -44,6 +61,7 @@ class CachedMapTileMetadata {
             return HttpDate.parse(expires);
           }
 
+          warnFallbackUsage();
           return addToNow(fallbackFreshnessAge);
         }
 
@@ -62,6 +80,7 @@ class CachedMapTileMetadata {
         return addToNow(Duration(seconds: int.parse(maxAge) - estimatedAge));
       }
 
+      warnFallbackUsage();
       return addToNow(fallbackFreshnessAge);
     }
 

lib/src/layer/tile_layer/tile_provider/network/image_provider/image_provider.dart

@@ -7,6 +7,7 @@ import 'package:flutter/painting.dart';
 import 'package:flutter_map/flutter_map.dart';
 import 'package:flutter_map/src/layer/tile_layer/tile_provider/network/image_provider/consolidate_response.dart';
 import 'package:http/http.dart';
+import 'package:logger/logger.dart';
 import 'package:meta/meta.dart';
 
 /// Dedicated [ImageProvider] to fetch tiles from the network
@@ -48,6 +49,9 @@ class NetworkTileImageProvider extends ImageProvider<NetworkTileImageProvider> {
   /// Whether to ignore exceptions and errors that occur whilst fetching tiles
   /// over the network, and just return a transparent tile
   ///
+  /// Also silences any exceptions generated when attempting to write tiles to
+  /// the cache.
+  ///
   /// Not included in [operator==].
   final bool silenceExceptions;
 
@@ -174,9 +178,26 @@ class NetworkTileImageProvider extends ImageProvider<NetworkTileImageProvider> {
       required Map<String, String> headers,
     }) {
       if (useFallback || !cachingProvider.isSupported) return;
+
+      late final CachedMapTileMetadata metadata;
+      try {
+        metadata = CachedMapTileMetadata.fromHttpHeaders(
+          headers,
+          warnOnFallbackUsage: silenceExceptions ? null : uri,
+        );
+      } catch (e) {
+        if (kDebugMode && !silenceExceptions) {
+          Logger(printer: SimplePrinter()).w(
+            '[flutter_map cache] Failed to cache ${uri.path}: $e\n\tThis may '
+            'indicate a HTTP spec non-conformance issue with the tile server. ',
+          );
+        }
+        return;
+      }
+
       cachingProvider.putTile(
         url: resolvedUrl,
-        metadata: CachedMapTileMetadata.fromHttpHeaders(headers),
+        metadata: metadata,
         bytes: bytes,
       );
     }

pubspec.yaml

@@ -1,6 +1,6 @@
 name: flutter_map
 description: "Flutter's №1 non-commercially aimed map client: it's easy-to-use, versatile, vendor-free, fully cross-platform, and 100% pure-Flutter"
-version: 8.2.0
+version: 8.2.1
 
 repository: https://github.com/fleaflet/flutter_map
 issue_tracker: https://github.com/fleaflet/flutter_map/issues

windowsApplicationInstallerSetup.iss

@@ -2,7 +2,7 @@
 ; SEE THE DOCUMENTATION FOR DETAILS ON CREATING INNO SETUP SCRIPT FILES!
 
 #define MyAppName "flutter_map Demo"
-#define MyAppVersion "for 8.2.0"
+#define MyAppVersion "for 8.2.1"
 #define MyAppPublisher "fleaflet"
 #define MyAppURL "https://github.com/fleaflet/flutter_map"
 #define MyAppSupportURL "https://github.com/fleaflet/flutter_map/issues"