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

@@ -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...)

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())
+	})
+})

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: