fix: resolve relative style/tileset URLs for OGC vector tiles (#1641)

* fix: resolve relative style/tileset URLs for OGC vector tiles

Adding an Esri vector tile service through Add Data -> OGC Vector Tiles
added the layer and then rendered nothing, with no error anywhere.

Every Esri vector tile style declares its tileset relatively:

    "sources": { "esri": { "type": "vector", "url": "../../" } }

`resolveOgcVectorTiles` copied that value straight into the MapLibre
source, and MapLibre resolves what it is handed against the *app* origin
rather than the document it came from -- so the source pointed at the
GeoLibre origin and never issued a single tile request. The `tiles`
form of a style source had the same flaw, as does an Esri
`VectorTileServer` document, which lists `tile/{z}/{y}/{x}.pbf`.

Resolve both forms against the document they were read from, and read
the tileset document behind a style's source URL so a non-TileJSON
service still yields usable absolute templates. `URL` percent-encodes
`{`/`}`, which would defeat MapLibre's placeholder substitution, so the
braces are restored after resolution.

Also surface Esri's HTTP 200 error bodies. ArcGIS reports a missing or
renamed service as 200 with `{"error":{"code":404,"message":...}}`, so
`response.ok` was true and the body parsed cleanly. That reached the
dialog as a valid-but-empty document and was reported as "no source
layers" -- hiding the real cause ("Requested Service not available.")
and sending the reporter looking for a nonexistent client problem.

Fixes #1639

* fix: surface ArcGIS error `details` when `message` is empty

ArcGIS routinely returns an error envelope whose `message` is an empty
string, with the only useful text in `details`. Asking a hosted
FeatureServer for a layer id it does not have answers:

    {"code":400,"message":"","details":
     ["The requested layer (layerId: 0) was not found."]}

Both error paths read `message` alone and fell back to a generic string,
so the Add Data dialog said "ArcGIS service request failed." and dropped
the one line naming what to correct. Prefer `message`, then `details`,
then the fallback.

* Address review feedback

- Do not read `code: 0` as a failure in `assertNoServiceError`: zero
  conventionally means success, so an envelope carrying only `code: 0`
  would have rejected a perfectly good document.
- Recognize a string `code` (`{"error":{"code":"NotFound"}}`) as a
  reported error. Only a numeric code counted before, so a host using
  string codes with no `message` slipped through as an empty document —
  the exact failure mode this check exists to catch.
- Add tests for the code-only branch (numeric 498 and a string code),
  and for the shapes that must *not* trip it: `code: 0`, and an `error`
  member that is a string, an array, or null.

Author: giswqs

apps/geolibre-desktop/src/lib/ogc-json.ts

@@ -79,6 +79,42 @@ async function responseStatusError(response: Response): Promise<Error> {
   }
 }
 
+/**
+ * Throws when a 2xx JSON document is really an Esri error report.
+ *
+ * ArcGIS answers a missing, renamed, or token-protected service with HTTP
+ * **200** and `{"error":{"code":404,"message":"Requested Service not
+ * available."}}`, so `response.ok` is true and the body parses cleanly. Left
+ * undetected it reaches the caller as a valid-but-empty document and surfaces
+ * as a misleading downstream complaint ("no source layers") instead of the
+ * actual cause.
+ *
+ * The shape is checked, not just the key: a legitimate document is free to
+ * carry an `error` property of some other form, so a `message` or a reported
+ * `code` is required before the document is rejected. `code: 0` conventionally
+ * means success, so it is not on its own a failure; a string code
+ * (`{"code":"NotFound"}`) is as much a report as a numeric one.
+ */
+function assertNoServiceError(doc: unknown): void {
+  const error = (doc as { error?: unknown } | null | undefined)?.error;
+  if (!error || typeof error !== "object" || Array.isArray(error)) return;
+  const { message, code, details } = error as {
+    message?: unknown;
+    code?: unknown;
+    details?: unknown;
+  };
+  const hasMessage = typeof message === "string" && message.trim() !== "";
+  const hasCode =
+    (typeof code === "number" && code !== 0) || (typeof code === "string" && code.trim() !== "");
+  if (!hasMessage && !hasCode) return;
+  // `details` is an array of extra lines; append it when it adds anything.
+  const detail = Array.isArray(details)
+    ? details.filter((line): line is string => typeof line === "string" && line.trim() !== "")
+    : [];
+  const text = hasMessage ? message.trim() : `Service error ${String(code).trim()}`;
+  throw new Error([text, ...detail].join(" ").slice(0, 300));
+}
+
 /**
  * Fetches and parses a remote JSON document, working around cross-origin limits
  * (see the module comment). When the caller passes a `signal` it owns the
@@ -106,7 +142,11 @@ export async function fetchOgcJson(
     try {
       const bytes = await Promise.race([bytesPromise, rejectOnAbort(abort)]);
       const array = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-      return JSON.parse(new TextDecoder().decode(array));
+      const doc = JSON.parse(new TextDecoder().decode(array));
+      // `normalizeFetchError` passes an Error through unchanged, so the service
+      // error message survives the catch below.
+      assertNoServiceError(doc);
+      return doc;
     } catch (error) {
       throw normalizeFetchError(error);
     }
@@ -122,5 +162,7 @@ export async function fetchOgcJson(
   if (!response.ok) {
     throw await responseStatusError(response);
   }
-  return response.json();
+  const doc = await response.json();
+  assertNoServiceError(doc);
+  return doc;
 }

apps/geolibre-desktop/src/lib/ogc-vector-tiles.ts

@@ -72,6 +72,12 @@ function asBounds(value: unknown): [number, number, number, number] | undefined
   return undefined;
 }
 
+/** Whether a reference already carries a scheme (or is protocol-relative), and
+ * so needs no resolution against the document it was read from. */
+function isAbsoluteUrl(value: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:/i.test(value) || value.startsWith("//");
+}
+
 /** Non-empty string tile templates from an unknown `tiles` value. */
 function asTiles(value: unknown): string[] | undefined {
   if (!Array.isArray(value)) return undefined;
@@ -251,6 +257,19 @@ export function tileJsonConfig(
   ) {
     config.center = center as number[];
   }
+  // An Esri `VectorTileServer` document is TileJSON-shaped enough to read
+  // (`name`, `maxzoom`) but lists its tiles relatively — `tile/{z}/{y}/{x}.pbf`.
+  // MapLibre would resolve those against the app origin, so when the document
+  // carries relative templates, hand it explicit absolute `tiles` instead of the
+  // document URL. Absolute templates are left alone so a conforming TileJSON
+  // keeps being loaded by MapLibre itself (it re-reads more than is copied here).
+  const tiles = asTiles(tilejson.tiles);
+  if (tiles?.some((tile) => !isAbsoluteUrl(tile))) {
+    config.tiles = tiles.map((tile) =>
+      normalizeTilePlaceholders(resolveDocumentUrl(tile, tilejsonUrl)),
+    );
+    delete config.url;
+  }
   const sourceLayers = vectorLayerIds(tilejson);
   if (sourceLayers.length > 0) config.sourceLayers = sourceLayers;
   return config;
@@ -263,6 +282,35 @@ function normalizeTilePlaceholders(url: string): string {
   return url.replace(/\{z\}/gi, "{z}").replace(/\{x\}/gi, "{x}").replace(/\{y\}/gi, "{y}");
 }
 
+/**
+ * Resolves a reference taken out of a fetched document against that document's
+ * own URL.
+ *
+ * Style and service documents routinely use relative references: every Esri
+ * vector tile style declares its tileset as `{"type":"vector","url":"../../"}`,
+ * and an Esri `VectorTileServer` document lists `tiles:
+ * ["tile/{z}/{y}/{x}.pbf"]`. MapLibre resolves whatever it is handed against
+ * the *app* origin rather than the document it came from, so passing such a
+ * value through verbatim requests the wrong host entirely — the layer is added
+ * and then silently renders nothing (GeoLibre#1639).
+ *
+ * `URL` percent-encodes the `{`/`}` of a tile template, which would defeat
+ * MapLibre's placeholder substitution, so the braces are restored afterwards.
+ *
+ * @param value - The (possibly relative) reference read from the document.
+ * @param baseUrl - The URL the document was fetched from.
+ * @returns The absolute URL, or the trimmed input when it cannot be resolved.
+ */
+export function resolveDocumentUrl(value: string, baseUrl?: string): string {
+  const trimmed = value.trim();
+  if (trimmed === "" || !baseUrl) return trimmed;
+  try {
+    return new URL(trimmed, baseUrl).toString().replace(/%7B/gi, "{").replace(/%7D/gi, "}");
+  } catch {
+    return trimmed;
+  }
+}
+
 /**
  * Resolves the configuration for an OGC API vector tiles layer from the URLs the
  * user provided, fetching the TileJSON and/or style document as needed.
@@ -324,12 +372,49 @@ export async function resolveOgcVectorTiles(input: {
     }
     if (vector) {
       // Fall back to the style's own vector source only when no tiles input was
-      // given...
+      // given. Both forms are resolved against the style URL first: they are
+      // routinely relative (see `resolveDocumentUrl`).
       if (!config.url && !config.tiles) {
         if (typeof vector.source.url === "string") {
-          config.url = vector.source.url;
+          const sourceUrl = resolveDocumentUrl(vector.source.url, styleUrl);
+          config.url = sourceUrl || undefined;
+          // The style only names the tileset; the document it points at holds
+          // the tile templates and zoom range. Read it so a non-TileJSON
+          // service (Esri's `VectorTileServer`) still yields usable absolute
+          // tiles. Best-effort: the style's own metadata below still applies if
+          // this fails, so a fetch error must not block adding the layer.
+          if (sourceUrl) {
+            const tileset = await fetchOgcJson(sourceUrl, signal).catch((error) => {
+              if (input.signal?.aborted) throw error;
+              return null;
+            });
+            if (tileset && typeof tileset === "object") {
+              // Style-derived source layers and name stay authoritative
+              // (manual > style > TileJSON), so the tileset must not clobber
+              // them. `url` is assigned rather than spread: `tileJsonConfig`
+              // *drops* it when it emits explicit `tiles`, and a spread would
+              // leave the stale value behind — a MapLibre vector source given
+              // both `url` and `tiles` is invalid.
+              const {
+                sourceLayers: tilesetLayers,
+                name: tilesetName,
+                url: tilesetUrl,
+                ...tilesetConfig
+              } = tileJsonConfig(tileset as Record<string, unknown>, sourceUrl);
+              config = {
+                ...config,
+                ...tilesetConfig,
+                url: tilesetUrl,
+                name: config.name ?? tilesetName,
+                sourceLayers:
+                  config.sourceLayers.length > 0 ? config.sourceLayers : (tilesetLayers ?? []),
+              };
+            }
+          }
         } else {
-          config.tiles = asTiles(vector.source.tiles)?.map(normalizeTilePlaceholders);
+          config.tiles = asTiles(vector.source.tiles)?.map((tile) =>
+            normalizeTilePlaceholders(resolveDocumentUrl(tile, styleUrl)),
+          );
         }
       }
       // ...but always fill a missing zoom range / bounds from the style, even

packages/plugins/src/plugins/arcgis-layer.ts

@@ -253,6 +253,35 @@ async function addArcGISFeatureLayerAsGeoJson(
   return id;
 }
 
+/** The JSON error envelope ArcGIS returns, usually with an HTTP 200 status. */
+interface ArcGISErrorEnvelope {
+  message?: string;
+  details?: unknown;
+}
+
+/**
+ * The most specific text available from an ArcGIS error envelope.
+ *
+ * `message` is frequently an empty string, with the only useful text in
+ * `details` — asking a hosted FeatureServer for a layer id it does not have
+ * answers `{"code":400,"message":"","details":["The requested layer (layerId:
+ * 0) was not found."]}`. Reading `message` alone drops that and reports the
+ * generic fallback, which says nothing about what to correct.
+ *
+ * @param error - The `error` member of an ArcGIS JSON response.
+ * @param fallback - The message to use when the envelope carries no text.
+ */
+function arcgisErrorMessage(error: ArcGISErrorEnvelope | undefined, fallback: string): string {
+  const message = typeof error?.message === "string" ? error.message.trim() : "";
+  if (message) return message;
+  const details = Array.isArray(error?.details)
+    ? error.details.filter(
+        (detail): detail is string => typeof detail === "string" && detail.trim() !== "",
+      )
+    : [];
+  return details.length > 0 ? details.join(" ").trim() : fallback;
+}
+
 /**
  * Fetch and validate a GeoJSON FeatureCollection from an ArcGIS query URL.
  *
@@ -281,7 +310,7 @@ async function fetchArcGISGeoJson(url: string): Promise<FeatureCollection> {
     );
   }
   let json: FeatureCollection & {
-    error?: { message?: string };
+    error?: ArcGISErrorEnvelope;
     exceededTransferLimit?: boolean;
   };
   try {
@@ -290,7 +319,7 @@ async function fetchArcGISGeoJson(url: string): Promise<FeatureCollection> {
     throw new Error("The ArcGIS feature layer did not return GeoJSON features.");
   }
   if (json.error) {
-    throw new Error(json.error.message || "ArcGIS feature query failed.");
+    throw new Error(arcgisErrorMessage(json.error, "ArcGIS feature query failed."));
   }
   if (json.type !== "FeatureCollection" || !Array.isArray(json.features)) {
     throw new Error("The ArcGIS feature layer did not return GeoJSON features.");
@@ -378,10 +407,10 @@ async function fetchArcGISJson<T>(
     });
   }
   const json = (await response.json()) as T & {
-    error?: { message?: string };
+    error?: ArcGISErrorEnvelope;
   };
   if (json.error) {
-    throw new Error(json.error.message || "ArcGIS service request failed.", {
+    throw new Error(arcgisErrorMessage(json.error, "ArcGIS service request failed."), {
       cause,
     });
   }

tests/arcgis-feature-layer.test.ts

@@ -149,6 +149,32 @@ describe("addArcGISLayer (feature layer)", () => {
     assert.equal(useAppStore.getState().layers.length, 0);
   });
 
+  // ArcGIS routinely leaves `message` empty and puts the only useful text in
+  // `details` — asking a hosted FeatureServer for a layer id it does not have
+  // answers `{"code":400,"message":"","details":["The requested layer (layerId:
+  // 0) was not found."]}`. Reporting the generic fallback instead hides the one
+  // thing the user needs to correct.
+  it("surfaces error `details` when the service leaves `message` empty", async () => {
+    globalThis.fetch = (async () =>
+      jsonResponse({
+        error: {
+          code: 400,
+          message: "",
+          details: ["The requested layer (layerId: 0) was not found."],
+        },
+      })) as typeof fetch;
+
+    await assert.rejects(
+      addArcGISLayer(app, {
+        layerType: "feature",
+        sourceType: "url",
+        url: "https://example.com/arcgis/rest/services/Cities/FeatureServer/0",
+      }),
+      /The requested layer \(layerId: 0\) was not found\./,
+    );
+    assert.equal(useAppStore.getState().layers.length, 0);
+  });
+
   it("rejects an HTML login page returned with a 200 status", async () => {
     globalThis.fetch = (async (input: RequestInfo | URL) => {
       const url = typeof input === "string" ? input : input.toString();