Fix enabled flag for custom classification models (#23681)

* honor enabled flag for custom classification models

for both startup and dynamically, even though the UI doesn't currently have a way to toggle dynamically

* add test

docs/docs/configuration/advanced/system.md

@@ -72,10 +72,10 @@ Variables prefixed with `FRIGATE_` can be referenced in config fields that suppo
 
 Navigate to <NavPath path="Settings > System > Environment variables" /> to add or edit environment variables.
 
-| Field     | Description                                               |
-| --------- | --------------------------------------------------------- |
-| **Key**   | The environment variable name (e.g., `FRIGATE_MQTT_USER`) |
-| **Value** | The value for the variable                                |
+| Field             | Description                                               |
+| ----------------- | --------------------------------------------------------- |
+| **Variable name** | The environment variable name (e.g., `FRIGATE_MQTT_USER`) |
+| **Value**         | The value for the variable                                |
 
 Variables defined here can be referenced elsewhere in your configuration using the `{FRIGATE_VARIABLE_NAME}` syntax.
 

docs/package-lock.json

@@ -367,12 +367,12 @@
       }
     },
     "node_modules/@babel/code-frame": {
-      "version": "7.29.0",
-      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.0.tgz",
-      "integrity": "sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==",
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.27.1.tgz",
+      "integrity": "sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg==",
       "license": "MIT",
       "dependencies": {
-        "@babel/helper-validator-identifier": "^7.28.5",
+        "@babel/helper-validator-identifier": "^7.27.1",
         "js-tokens": "^4.0.0",
         "picocolors": "^1.1.1"
       },
@@ -429,13 +429,13 @@
       }
     },
     "node_modules/@babel/generator": {
-      "version": "7.29.1",
-      "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.29.1.tgz",
-      "integrity": "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==",
+      "version": "7.28.5",
+      "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.28.5.tgz",
+      "integrity": "sha512-3EwLFhZ38J4VyIP6WNtt2kUdW9dokXA9Cr4IVIFHuCpZ3H8/YFOl5JjZHisrn1fATPBmKKqXzDFvh9fUwHz6CQ==",
       "license": "MIT",
       "dependencies": {
-        "@babel/parser": "^7.29.0",
-        "@babel/types": "^7.29.0",
+        "@babel/parser": "^7.28.5",
+        "@babel/types": "^7.28.5",
         "@jridgewell/gen-mapping": "^0.3.12",
         "@jridgewell/trace-mapping": "^0.3.28",
         "jsesc": "^3.0.2"
@@ -576,27 +576,27 @@
       }
     },
     "node_modules/@babel/helper-module-imports": {
-      "version": "7.28.6",
-      "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.28.6.tgz",
-      "integrity": "sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==",
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.27.1.tgz",
+      "integrity": "sha512-0gSFWUPNXNopqtIPQvlD5WgXYI5GY2kP2cCvoT8kczjbfcfuIljTbcWrulD1CIPIX2gt1wghbDy08yE1p+/r3w==",
       "license": "MIT",
       "dependencies": {
-        "@babel/traverse": "^7.28.6",
-        "@babel/types": "^7.28.6"
+        "@babel/traverse": "^7.27.1",
+        "@babel/types": "^7.27.1"
       },
       "engines": {
         "node": ">=6.9.0"
       }
     },
     "node_modules/@babel/helper-module-transforms": {
-      "version": "7.28.6",
-      "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.28.6.tgz",
-      "integrity": "sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==",
+      "version": "7.28.3",
+      "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.28.3.tgz",
+      "integrity": "sha512-gytXUbs8k2sXS9PnQptz5o0QnpLL51SwASIORY6XaBKF88nsOT0Zw9szLqlSGQDP/4TljBAD5y98p2U1fqkdsw==",
       "license": "MIT",
       "dependencies": {
-        "@babel/helper-module-imports": "^7.28.6",
-        "@babel/helper-validator-identifier": "^7.28.5",
-        "@babel/traverse": "^7.28.6"
+        "@babel/helper-module-imports": "^7.27.1",
+        "@babel/helper-validator-identifier": "^7.27.1",
+        "@babel/traverse": "^7.28.3"
       },
       "engines": {
         "node": ">=6.9.0"
@@ -618,9 +618,9 @@
       }
     },
     "node_modules/@babel/helper-plugin-utils": {
-      "version": "7.28.6",
-      "resolved": "https://registry.npmjs.org/@babel/helper-plugin-utils/-/helper-plugin-utils-7.28.6.tgz",
-      "integrity": "sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug==",
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/helper-plugin-utils/-/helper-plugin-utils-7.27.1.tgz",
+      "integrity": "sha512-1gn1Up5YXka3YYAHGKpbideQ5Yjf1tDa9qYcgysz+cNCXukyLl6DjPXhD3VRwSb8c0J9tA4b2+rHEZtc6R0tlw==",
       "license": "MIT",
       "engines": {
         "node": ">=6.9.0"
@@ -728,12 +728,12 @@
       }
     },
     "node_modules/@babel/parser": {
-      "version": "7.29.3",
-      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.3.tgz",
-      "integrity": "sha512-b3ctpQwp+PROvU/cttc4OYl4MzfJUWy6FZg+PMXfzmt/+39iHVF0sDfqay8TQM3JA2EUOyKcFZt75jWriQijsA==",
+      "version": "7.28.5",
+      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.28.5.tgz",
+      "integrity": "sha512-KKBU1VGYR7ORr3At5HAtUQ+TV3SzRCXmA/8OdDZiLDBIZxVyzXuztPjfLd3BV1PRAQGCMWWSHYhL0F8d5uHBDQ==",
       "license": "MIT",
       "dependencies": {
-        "@babel/types": "^7.29.0"
+        "@babel/types": "^7.28.5"
       },
       "bin": {
         "parser": "bin/babel-parser.js"
@@ -1318,15 +1318,15 @@
       }
     },
     "node_modules/@babel/plugin-transform-modules-systemjs": {
-      "version": "7.29.4",
-      "resolved": "https://registry.npmjs.org/@babel/plugin-transform-modules-systemjs/-/plugin-transform-modules-systemjs-7.29.4.tgz",
-      "integrity": "sha512-N7QmZ0xRZfjHOfZeQLJjwgX2zS9pdGHSVl/cjSGlo4dXMqvurfxXDMKY4RqEKzPozV78VMcd0lxyG13mlbKc4w==",
+      "version": "7.28.5",
+      "resolved": "https://registry.npmjs.org/@babel/plugin-transform-modules-systemjs/-/plugin-transform-modules-systemjs-7.28.5.tgz",
+      "integrity": "sha512-vn5Jma98LCOeBy/KpeQhXcV2WZgaRUtjwQmjoBuLNlOmkg0fB5pdvYVeWRYI69wWKwK2cD1QbMiUQnoujWvrew==",
       "license": "MIT",
       "dependencies": {
-        "@babel/helper-module-transforms": "^7.28.6",
-        "@babel/helper-plugin-utils": "^7.28.6",
+        "@babel/helper-module-transforms": "^7.28.3",
+        "@babel/helper-plugin-utils": "^7.27.1",
         "@babel/helper-validator-identifier": "^7.28.5",
-        "@babel/traverse": "^7.29.0"
+        "@babel/traverse": "^7.28.5"
       },
       "engines": {
         "node": ">=6.9.0"
@@ -2022,31 +2022,31 @@
       }
     },
     "node_modules/@babel/template": {
-      "version": "7.28.6",
-      "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.28.6.tgz",
-      "integrity": "sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==",
+      "version": "7.27.2",
+      "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.27.2.tgz",
+      "integrity": "sha512-LPDZ85aEJyYSd18/DkjNh4/y1ntkE5KwUHWTiqgRxruuZL2F1yuHligVHLvcHY2vMHXttKFpJn6LwfI7cw7ODw==",
       "license": "MIT",
       "dependencies": {
-        "@babel/code-frame": "^7.28.6",
-        "@babel/parser": "^7.28.6",
-        "@babel/types": "^7.28.6"
+        "@babel/code-frame": "^7.27.1",
+        "@babel/parser": "^7.27.2",
+        "@babel/types": "^7.27.1"
       },
       "engines": {
         "node": ">=6.9.0"
       }
     },
     "node_modules/@babel/traverse": {
-      "version": "7.29.0",
-      "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.0.tgz",
-      "integrity": "sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==",
+      "version": "7.28.5",
+      "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.28.5.tgz",
+      "integrity": "sha512-TCCj4t55U90khlYkVV/0TfkJkAkUg3jZFA3Neb7unZT8CPok7iiRfaX0F+WnqWqt7OxhOn0uBKXCw4lbL8W0aQ==",
       "license": "MIT",
       "dependencies": {
-        "@babel/code-frame": "^7.29.0",
-        "@babel/generator": "^7.29.0",
+        "@babel/code-frame": "^7.27.1",
+        "@babel/generator": "^7.28.5",
         "@babel/helper-globals": "^7.28.0",
-        "@babel/parser": "^7.29.0",
-        "@babel/template": "^7.28.6",
-        "@babel/types": "^7.29.0",
+        "@babel/parser": "^7.28.5",
+        "@babel/template": "^7.27.2",
+        "@babel/types": "^7.28.5",
         "debug": "^4.3.1"
       },
       "engines": {
@@ -2054,9 +2054,9 @@
       }
     },
     "node_modules/@babel/types": {
-      "version": "7.29.0",
-      "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.0.tgz",
-      "integrity": "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==",
+      "version": "7.28.5",
+      "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.28.5.tgz",
+      "integrity": "sha512-qQ5m48eI/MFLQ5PxQj4PFaprjyCTLI37ElWMmNs0K8Lk3dVeOdNpB3ks8jc7yM5CDmVC73eMVk/trk3fgmrUpA==",
       "license": "MIT",
       "dependencies": {
         "@babel/helper-string-parser": "^7.27.1",

frigate/embeddings/maintainer.py

@@ -200,6 +200,9 @@ class EmbeddingMaintainer(threading.Thread):
             )
 
         for model_config in self.config.classification.custom.values():
+            if not model_config.enabled:
+                continue
+
             self.realtime_processors.append(
                 CustomStateClassificationProcessor(
                     self.config, model_config, self.requestor, self.metrics
@@ -332,6 +335,25 @@ class EmbeddingMaintainer(threading.Thread):
         for processor in self.post_processors:
             processor.update_config(topic, payload)
 
+    def _remove_custom_classification_processor(self, model_name: str) -> None:
+        """Shut down and drop any running processor for a custom model."""
+        remaining = []
+        for processor in self.realtime_processors:
+            if (
+                isinstance(
+                    processor,
+                    (
+                        CustomStateClassificationProcessor,
+                        CustomObjectClassificationProcessor,
+                    ),
+                )
+                and processor.model_config.name == model_name
+            ):
+                processor.shutdown()
+            else:
+                remaining.append(processor)
+        self.realtime_processors = remaining
+
     def _handle_custom_classification_update(
         self, topic: str, model_config: Any
     ) -> None:
@@ -339,23 +361,7 @@ class EmbeddingMaintainer(threading.Thread):
         model_name = topic.split("/")[-1]
 
         if model_config is None:
-            remaining = []
-            for processor in self.realtime_processors:
-                if (
-                    isinstance(
-                        processor,
-                        (
-                            CustomStateClassificationProcessor,
-                            CustomObjectClassificationProcessor,
-                        ),
-                    )
-                    and processor.model_config.name == model_name
-                ):
-                    processor.shutdown()
-                else:
-                    remaining.append(processor)
-            self.realtime_processors = remaining
-
+            self._remove_custom_classification_processor(model_name)
             logger.info(
                 f"Successfully removed classification processor for model: {model_name}"
             )
@@ -363,6 +369,13 @@ class EmbeddingMaintainer(threading.Thread):
 
         self.config.classification.custom[model_name] = model_config
 
+        # A disabled model must not run; tear down any existing processor and
+        # do not register a new one.
+        if not model_config.enabled:
+            self._remove_custom_classification_processor(model_name)
+            logger.info(f"Disabled classification processor for model: {model_name}")
+            return
+
         # Check if processor already exists
         for processor in self.realtime_processors:
             if isinstance(
@@ -702,7 +715,11 @@ class EmbeddingMaintainer(threading.Thread):
             and "license_plate" not in camera_config.objects.track
         )
 
-        if not dedicated_lpr_enabled and len(self.config.classification.custom) == 0:
+        has_enabled_custom = any(
+            c.enabled for c in self.config.classification.custom.values()
+        )
+
+        if not dedicated_lpr_enabled and not has_enabled_custom:
             # no active features that use this data
             return
 

frigate/test/test_classification_enabled.py

@@ -0,0 +1,106 @@
+"""Tests that disabled custom classification models are not registered or run."""
+
+import sys
+import unittest
+from unittest.mock import MagicMock
+
+# Mock TFLite before importing the maintainer / classification modules
+_MOCK_MODULES = [
+    "tflite_runtime",
+    "tflite_runtime.interpreter",
+    "ai_edge_litert",
+    "ai_edge_litert.interpreter",
+]
+for mod in _MOCK_MODULES:
+    if mod not in sys.modules:
+        sys.modules[mod] = MagicMock()
+
+from frigate.data_processing.real_time.custom_classification import (  # noqa: E402
+    CustomObjectClassificationProcessor,
+)
+from frigate.embeddings.maintainer import EmbeddingMaintainer  # noqa: E402
+
+
+class TestCustomClassificationEnabledGating(unittest.TestCase):
+    """A model with enabled: false must not keep a processor registered."""
+
+    def _make_maintainer(self) -> EmbeddingMaintainer:
+        # Bypass the heavy __init__; only the attributes touched by the
+        # config update path are needed for these tests.
+        maintainer = EmbeddingMaintainer.__new__(EmbeddingMaintainer)
+        maintainer.realtime_processors = []
+        maintainer.config = MagicMock()
+        maintainer.config.classification.custom = {}
+        maintainer.requestor = MagicMock()
+        maintainer.metrics = MagicMock()
+        maintainer.event_metadata_publisher = MagicMock()
+        return maintainer
+
+    def _make_model_config(self, name: str, enabled: bool) -> MagicMock:
+        model_config = MagicMock()
+        model_config.name = name
+        model_config.enabled = enabled
+        model_config.state_config = None
+        return model_config
+
+    def _make_processor(self, name: str) -> MagicMock:
+        processor = MagicMock(spec=CustomObjectClassificationProcessor)
+        processor.model_config = MagicMock()
+        processor.model_config.name = name
+        return processor
+
+    def test_disabled_update_tears_down_existing_processor(self):
+        """Toggling a running model to disabled shuts down and drops its processor."""
+        maintainer = self._make_maintainer()
+        processor = self._make_processor("atli")
+        maintainer.realtime_processors = [processor]
+
+        maintainer._handle_custom_classification_update(
+            "config/classification/custom/atli",
+            self._make_model_config("atli", enabled=False),
+        )
+
+        processor.shutdown.assert_called_once()
+        self.assertEqual(maintainer.realtime_processors, [])
+
+    def test_disabled_update_does_not_register_processor(self):
+        """A disabled model that has no processor is never registered."""
+        maintainer = self._make_maintainer()
+
+        maintainer._handle_custom_classification_update(
+            "config/classification/custom/atli",
+            self._make_model_config("atli", enabled=False),
+        )
+
+        self.assertEqual(maintainer.realtime_processors, [])
+
+    def test_disabled_update_leaves_other_processors_untouched(self):
+        """Disabling one model must not affect other running processors."""
+        maintainer = self._make_maintainer()
+        other = self._make_processor("simbi")
+        maintainer.realtime_processors = [other]
+
+        maintainer._handle_custom_classification_update(
+            "config/classification/custom/atli",
+            self._make_model_config("atli", enabled=False),
+        )
+
+        other.shutdown.assert_not_called()
+        self.assertEqual(maintainer.realtime_processors, [other])
+
+    def test_removed_model_tears_down_processor(self):
+        """A None payload (model deleted) still shuts down its processor."""
+        maintainer = self._make_maintainer()
+        processor = self._make_processor("atli")
+        maintainer.realtime_processors = [processor]
+
+        maintainer._handle_custom_classification_update(
+            "config/classification/custom/atli", None
+        )
+
+        processor.shutdown.assert_called_once()
+        self.assertEqual(maintainer.realtime_processors, [])
+
+
+if __name__ == "__main__":
+    unittest.main()

web/public/locales/en/views/settings.json

@@ -1490,7 +1490,14 @@
       "keyLabel": "Key",
       "valueLabel": "Value",
       "keyPlaceholder": "New key",
-      "remove": "Remove"
+      "remove": "Remove",
+      "providerNameLabel": "Provider name",
+      "providerNamePlaceholder": "e.g., openai",
+      "variableNameLabel": "Variable name",
+      "variableNamePlaceholder": "e.g., MY_VARIABLE",
+      "loggerNameLabel": "Logger name",
+      "loggerNamePlaceholder": "e.g., frigate.record",
+      "keyPatternError": "Use only letters, numbers, hyphens, and underscores (no spaces)"
     },
     "knownPlates": {
       "namePlaceholder": "e.g., Wife's Car",

web/src/components/config-form/section-configs/environment_vars.ts

@@ -7,7 +7,13 @@ const environmentVars: SectionConfigOverrides = {
     advancedFields: [],
     uiSchema: {
       additionalProperties: {
-        "ui:options": { size: "lg" },
+        "ui:options": {
+          size: "lg",
+          additionalPropertyKeyLabel:
+            "configForm.additionalProperties.variableNameLabel",
+          additionalPropertyKeyPlaceholder:
+            "configForm.additionalProperties.variableNamePlaceholder",
+        },
       },
     },
   },

web/src/components/config-form/section-configs/genai.ts

@@ -9,7 +9,15 @@ const genai: SectionConfigOverrides = {
     uiSchema: {
       "ui:options": { disableNestedCard: true },
       "*": {
-        "ui:options": { disableNestedCard: true },
+        "ui:options": {
+          disableNestedCard: true,
+          additionalPropertyKeyLabel:
+            "configForm.additionalProperties.providerNameLabel",
+          additionalPropertyKeyPlaceholder:
+            "configForm.additionalProperties.providerNamePlaceholder",
+          additionalPropertyKeyPattern: "^[a-zA-Z0-9_-]+$",
+          preventKeyRename: true,
+        },
         "ui:order": [
           "provider",
           "api_key",

web/src/components/config-form/section-configs/logger.ts

@@ -12,7 +12,13 @@ const logger: SectionConfigOverrides = {
       },
       logs: {
         additionalProperties: {
-          "ui:options": { enumI18nPrefix: "logger.logLevel" },
+          "ui:options": {
+            enumI18nPrefix: "logger.logLevel",
+            additionalPropertyKeyLabel:
+              "configForm.additionalProperties.loggerNameLabel",
+            additionalPropertyKeyPlaceholder:
+              "configForm.additionalProperties.loggerNamePlaceholder",
+          },
         },
       },
     },

web/src/components/config-form/theme/templates/WrapIfAdditionalTemplate.tsx

@@ -6,12 +6,14 @@ import {
   StrictRJSFSchema,
   WrapIfAdditionalTemplateProps,
 } from "@rjsf/utils";
+import { useEffect, useMemo, useState, type FocusEvent } from "react";
 import { Input } from "@/components/ui/input";
 import { Button } from "@/components/ui/button";
 import { Label } from "@/components/ui/label";
 import { cn } from "@/lib/utils";
 import { useTranslation } from "react-i18next";
 import { LuTrash2 } from "react-icons/lu";
+import type { ConfigFormContext } from "@/types/configForm";
 
 export function WrapIfAdditionalTemplate<
   T = unknown,
@@ -30,6 +32,7 @@ export function WrapIfAdditionalTemplate<
     onKeyRenameBlur,
     readonly,
     required,
+    registry,
     schema,
     uiSchema,
   } = props;
@@ -38,6 +41,55 @@ export function WrapIfAdditionalTemplate<
 
   const additional = ADDITIONAL_PROPERTY_FLAG in schema;
 
+  const uiOptions = getUiOptions(uiSchema);
+  const keyIsReadonly = uiOptions.additionalPropertyKeyReadonly === true;
+
+  const keyLabelKey =
+    typeof uiOptions.additionalPropertyKeyLabel === "string"
+      ? uiOptions.additionalPropertyKeyLabel
+      : undefined;
+  const keyPlaceholderKey =
+    typeof uiOptions.additionalPropertyKeyPlaceholder === "string"
+      ? uiOptions.additionalPropertyKeyPlaceholder
+      : undefined;
+  const keyPattern =
+    typeof uiOptions.additionalPropertyKeyPattern === "string"
+      ? uiOptions.additionalPropertyKeyPattern
+      : undefined;
+  const preventKeyRename = uiOptions.preventKeyRename === true;
+
+  const formContext = registry?.formContext as ConfigFormContext | undefined;
+
+  // optionally, lock the key once it's been saved
+  const baseline = formContext?.baselineFormData;
+  const keyLocked =
+    preventKeyRename &&
+    typeof label === "string" &&
+    !!baseline &&
+    Object.prototype.hasOwnProperty.call(baseline, label);
+
+  // controlled key value so we can validate live and block invalid renames.
+  const [keyValue, setKeyValue] = useState<string>(label ?? "");
+  useEffect(() => {
+    setKeyValue(label ?? "");
+  }, [label]);
+
+  const keyRegex = useMemo(
+    () => (keyPattern ? new RegExp(keyPattern) : undefined),
+    [keyPattern],
+  );
+  const keyError = useMemo(() => {
+    if (!keyRegex || keyLocked) return null;
+    if (!keyRegex.test(keyValue)) {
+      return t("configForm.additionalProperties.keyPatternError", {
+        ns: "views/settings",
+        defaultValue:
+          "Use only letters, numbers, hyphens, and underscores (no spaces)",
+      });
+    }
+    return null;
+  }, [keyRegex, keyLocked, keyValue, t]);
+
   if (!additional) {
     return (
       <div className={classNames} style={style}>
@@ -47,20 +99,26 @@ export function WrapIfAdditionalTemplate<
   }
 
   const keyId = `${id}-key`;
-  const keyLabel = t("configForm.additionalProperties.keyLabel", {
-    ns: "views/settings",
-  });
+  const keyLabel = keyLabelKey
+    ? t(keyLabelKey, { ns: "views/settings" })
+    : t("configForm.additionalProperties.keyLabel", { ns: "views/settings" });
   const valueLabel = t("configForm.additionalProperties.valueLabel", {
     ns: "views/settings",
   });
-  const keyPlaceholder = t("configForm.additionalProperties.keyPlaceholder", {
-    ns: "views/settings",
-  });
+  const keyPlaceholder = keyPlaceholderKey
+    ? t(keyPlaceholderKey, { ns: "views/settings" })
+    : t("configForm.additionalProperties.keyPlaceholder", {
+        ns: "views/settings",
+      });
   const removeLabel = t("configForm.additionalProperties.remove", {
     ns: "views/settings",
   });
-  const uiOptions = getUiOptions(uiSchema);
-  const keyIsReadonly = uiOptions.additionalPropertyKeyReadonly === true;
+
+  const commitKeyRename = (e: FocusEvent<HTMLInputElement>) => {
+    if (readonly) return;
+    if (keyError) return;
+    onKeyRenameBlur?.(e);
+  };
 
   return (
     <div
@@ -70,23 +128,30 @@ export function WrapIfAdditionalTemplate<
       {!keyIsReadonly && (
         <div className="col-span-12 space-y-2 md:col-span-2">
           {displayLabel && <Label htmlFor={keyId}>{keyLabel}</Label>}
-          {keyIsReadonly ? (
+          {keyLocked ? (
             <div
               id={keyId}
-              className="flex items-center text-sm text-muted-foreground"
+              className="flex items-center break-all text-sm text-primary-variant"
             >
               {label}
             </div>
           ) : (
-            <Input
-              id={keyId}
-              name={keyId}
-              required={required}
-              defaultValue={label}
-              placeholder={keyPlaceholder}
-              disabled={disabled || readonly}
-              onBlur={!readonly ? onKeyRenameBlur : undefined}
-            />
+            <>
+              <Input
+                id={keyId}
+                name={keyId}
+                required={required}
+                value={keyValue}
+                placeholder={keyPlaceholder}
+                disabled={disabled || readonly}
+                onChange={(e) => setKeyValue(e.target.value)}
+                onBlur={!readonly ? commitKeyRename : undefined}
+                aria-invalid={keyError ? true : undefined}
+              />
+              {keyError && (
+                <p className="text-xs text-destructive">{keyError}</p>
+              )}
+            </>
           )}
         </div>
       )}