From 0847cc19fb25232c35291a7a8326d05a6aaaf6fa Mon Sep 17 00:00:00 2001
From: Goooler <wangzongler@gmail.com>
Date: Mon, 12 Oct 2026 17:54:15 +0800
Subject: [PATCH] Fail fast with setup instructions when SDK_REGISTRY_TOKEN is
 missing

A missing token used to surface as "Could not get unknown property 'SDK_REGISTRY_TOKEN'" and a public (pk.) token as an HTTP 403 during dependency resolution. Check the token in the settings scripts of the
root and compose builds and point to where a secret token with the `DOWNLOADS:READ` scope can be created.
---
 DEVELOPING.md                                 | 11 ++++++-
 compose/settings.gradle.kts                   |  2 ++
 gradle/sdk-registry-token.settings.gradle.kts | 30 +++++++++++++++++++
 settings.gradle.kts                           |  2 ++
 4 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 gradle/sdk-registry-token.settings.gradle.kts

diff --git a/DEVELOPING.md b/DEVELOPING.md
index 61a1731827..86d8ed6934 100644
--- a/DEVELOPING.md
+++ b/DEVELOPING.md
@@ -64,9 +64,18 @@ or update them inline in the source code:
 
 The SDK_REGISTRY_TOKEN is a Mapbox access token, used during compile time, with a scope set to `DOWNLOADS:READ`.
 This token allows to download all required Mapbox dependencies from a Mapbox Maven instance.
-The DOWNLOADS:READ scope can be set when creating a new access token on https://account.mapbox.com/.
+The DOWNLOADS:READ scope can be set when creating a new access token on https://account.mapbox.com/access-tokens/.
+It is a secret scope, so the resulting token is a secret token starting with `sk.`; a public token (`pk.`) will not work.
 The token configuration can be found in the root `build.gradle.kts` of the project.
 
+Besides exporting it as an environment variable, the token can also be set as a Gradle property in `~/.gradle/gradle.properties`:
+
+```
+SDK_REGISTRY_TOKEN=sk.xxx
+```
+
+The build fails early with setup instructions if the token is missing.
+
 #### Mapbox Access token
 
 The MAPBOX_ACCESS_TOKEN is a mapbox access token, packaged as part of test application, to load Mapbox tiles and resources.
diff --git a/compose/settings.gradle.kts b/compose/settings.gradle.kts
index 97d98061f5..0943012dc0 100644
--- a/compose/settings.gradle.kts
+++ b/compose/settings.gradle.kts
@@ -7,6 +7,8 @@ pluginManagement {
   includeBuild("../mapbox-convention-plugin")
 }
 
+apply(from = "../gradle/sdk-registry-token.settings.gradle.kts")
+
 dependencyResolutionManagement {
   versionCatalogs {
     create("libs") {
diff --git a/gradle/sdk-registry-token.settings.gradle.kts b/gradle/sdk-registry-token.settings.gradle.kts
new file mode 100644
index 0000000000..48018016af
--- /dev/null
+++ b/gradle/sdk-registry-token.settings.gradle.kts
@@ -0,0 +1,30 @@
+// Fails fast with setup instructions when the token needed to download Mapbox dependencies is
+// missing or of the wrong kind, instead of an "unknown property" or HTTP 401/403 error later on.
+val sdkRegistryToken = providers.environmentVariable("SDK_REGISTRY_TOKEN")
+  .orElse(providers.gradleProperty("SDK_REGISTRY_TOKEN"))
+  .orNull
+
+val problem = when {
+  sdkRegistryToken.isNullOrBlank() -> "SDK_REGISTRY_TOKEN is not set."
+  sdkRegistryToken.startsWith("pk.") ->
+    "SDK_REGISTRY_TOKEN is a public token (pk.), but a secret token (sk.) is required."
+  else -> null
+}
+
+if (problem != null) {
+  throw GradleException(
+    """
+    |$problem
+    |
+    |Building this project requires a Mapbox secret access token with the DOWNLOADS:READ scope:
+    |  1. Sign up or log in at https://account.mapbox.com/
+    |  2. Create a token at https://account.mapbox.com/access-tokens/ with the DOWNLOADS:READ
+    |     secret scope checked, and copy the generated token (it starts with "sk.").
+    |  3. Either export it as the SDK_REGISTRY_TOKEN environment variable, or add it to
+    |     ~/.gradle/gradle.properties:
+    |       SDK_REGISTRY_TOKEN=sk.xxx
+    |
+    |See DEVELOPING.md for more details.
+    """.trimMargin()
+  )
+}
diff --git a/settings.gradle.kts b/settings.gradle.kts
index add98f3473..6430b8699d 100644
--- a/settings.gradle.kts
+++ b/settings.gradle.kts
@@ -7,6 +7,8 @@ pluginManagement {
   includeBuild("mapbox-convention-plugin")
 }
 
+apply(from = "gradle/sdk-registry-token.settings.gradle.kts")
+
 dependencyResolutionManagement {
   versionCatalogs {
     create("commonLibs") {