From 0bfddb34527af6d288246e5331ee0f6de0db8e2d Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 18 May 2026 13:18:30 +0000
Subject: [PATCH] docs: document custom GeoJSON URL requirements for area maps

---
 references/chart-types/map.mdx | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/references/chart-types/map.mdx b/references/chart-types/map.mdx
index f1cba03b..71b95cc1 100644
--- a/references/chart-types/map.mdx
+++ b/references/chart-types/map.mdx
@@ -87,6 +87,18 @@ For example, if your GeoJSON has a `postal_code` property and your data has a `z
 2. Select `postal_code` from the **Map join field** dropdown
 3. Select your `zip_code` field as the **Data join field**
 
+##### Custom GeoJSON URL requirements
+
+Lightdash fetches custom GeoJSON files through a server-side proxy that enforces the following requirements:
+
+- The URL must use **HTTPS**.
+- The file path must end in `.json`, `.geojson`, or `.topojson`.
+- The file must be **10 MB or smaller** and the host must respond within **30 seconds**.
+- The host must be a public address. URLs that resolve to private, loopback, link-local, multicast, or carrier-grade NAT IP ranges are rejected.
+- **Redirects are not followed.** Host your file at a stable URL that responds with `200 OK` directly.
+
+If a URL fails these checks, the **Map join field** dropdown stays empty and the chart shows an error. Re-upload the file to a public HTTPS host (for example, a CDN or object storage bucket with public read access) and try again.
+
 ### Display options
 
 | Option | Description |