From daa8d2adbd6f0dd460e5ad15e37cf6f78c6aa187 Mon Sep 17 00:00:00 2001
From: localai-org-maint-bot <bot-opensource@localaisrl.com>
Date: Mon, 10 Aug 2026 00:18:01 +0200
Subject: [PATCH] fix(gallery): identify invalid preload JSON (#11434)

Wrap PRELOAD_MODELS decoding failures with the setting name and expected top-level shape so startup errors point directly to the invalid configuration. Document the required array format and cover scalar and empty-array inputs.

Assisted-by: Codex:gpt-5

Co-authored-by: localai-org-maint-bot <306269227+localai-org-maint-bot@users.noreply.github.com>
---
 core/services/galleryop/models.go             |  5 ++-
 .../services/galleryop/models_preload_test.go | 32 +++++++++++++++++++
 docs/content/features/model-gallery.md        |  2 ++
 3 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 core/services/galleryop/models_preload_test.go

diff --git a/core/services/galleryop/models.go b/core/services/galleryop/models.go
index 792618604..797794d5e 100644
--- a/core/services/galleryop/models.go
+++ b/core/services/galleryop/models.go
@@ -230,7 +230,10 @@ func ApplyGalleryFromString(systemState *system.SystemState, modelLoader *model.
 	var requests []galleryModel
 	err := json.Unmarshal([]byte(s), &requests)
 	if err != nil {
-		return err
+		return fmt.Errorf("invalid PRELOAD_MODELS/--preload-models value: expected a JSON array of model requests: %w", err)
+	}
+	if requests == nil {
+		return fmt.Errorf("invalid PRELOAD_MODELS/--preload-models value: expected a JSON array of model requests")
 	}
 
 	return processRequests(systemState, modelLoader, enforceScan, automaticallyInstallBackend, galleries, backendGalleries, requests, requireBackendIntegrity, options...)
diff --git a/core/services/galleryop/models_preload_test.go b/core/services/galleryop/models_preload_test.go
new file mode 100644
index 000000000..144084154
--- /dev/null
+++ b/core/services/galleryop/models_preload_test.go
@@ -0,0 +1,32 @@
+package galleryop_test
+
+import (
+	"github.com/mudler/LocalAI/core/services/galleryop"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("JSON model preloads", func() {
+	It("identifies PRELOAD_MODELS when the value is not a JSON array", func() {
+		err := galleryop.ApplyGalleryFromString(nil, nil, false, false, nil, nil, "true", false)
+
+		Expect(err).To(MatchError(And(
+			ContainSubstring("PRELOAD_MODELS/--preload-models"),
+			ContainSubstring("expected a JSON array"),
+		)))
+	})
+
+	It("rejects a null PRELOAD_MODELS value", func() {
+		err := galleryop.ApplyGalleryFromString(nil, nil, false, false, nil, nil, "null", false)
+
+		Expect(err).To(MatchError(And(
+			ContainSubstring("PRELOAD_MODELS/--preload-models"),
+			ContainSubstring("expected a JSON array"),
+		)))
+	})
+
+	It("accepts an empty JSON array", func() {
+		Expect(galleryop.ApplyGalleryFromString(nil, nil, false, false, nil, nil, "[]", false)).To(Succeed())
+	})
+})
diff --git a/docs/content/features/model-gallery.md b/docs/content/features/model-gallery.md
index e5d3ce656..9f54b720b 100644
--- a/docs/content/features/model-gallery.md
+++ b/docs/content/features/model-gallery.md
@@ -400,6 +400,8 @@ To preload models on start, use the `PRELOAD_MODELS` environment variable by set
 PRELOAD_MODELS='[{"url": "<MODEL_URL>"}]'
 ```
 
+The value must be a JSON array. Boolean values such as `true` are not valid model preload configurations.
+
 Note: `url` or `id` must be specified. `url` is used to a url to a model gallery configuration, while an `id` is used to refer to models inside repositories. If both are specified, the `id` will be used.
 
 For example: