Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(config): warn when unknown config fields are ignored (#5193)

Johnny1f1c46e11bf6
diff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.md
index f26bc455e..c632bc078 100644
--- a/docs/en/configuration/01-server.md
+++ b/docs/en/configuration/01-server.md
@@ -36,7 +36,7 @@ The server reads the file at startup. Restart the server after changing models,
}
```
-Optional sections use their defaults when omitted. Unknown fields in `ov.conf` and persisted account settings are ignored for upgrade compatibility. Known fields still validate types and values; misspelled field names are also ignored.
+Optional sections use their defaults when omitted. Unknown fields in `ov.conf` and persisted account settings are ignored for upgrade compatibility. Known fields still validate types and values. Misspelled field names are also ignored, but the server logs a warning listing every field it did not apply.
## Top-Level Settings
diff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.md
index 956de6ce8..4d835023d 100644
--- a/docs/zh/configuration/01-server.md
+++ b/docs/zh/configuration/01-server.md
@@ -36,7 +36,7 @@ openviking-server --config /path/to/ov.conf
}
```
-未配置的可选模块使用默认值。`ov.conf` 及账户配置会忽略未知字段,兼容旧版本遗留配置;已知字段仍校验类型和取值。字段名拼写错误也会被忽略。
+未配置的可选模块使用默认值。`ov.conf` 及账户配置会忽略未知字段,兼容旧版本遗留配置;已知字段仍校验类型和取值。字段名拼写错误也会被忽略,但服务端会输出 WARNING,逐项列出未被采用的字段。
## 顶层配置
diff --git a/openviking/config/binding.py b/openviking/config/binding.py
index 4d4dbe016..4f90e70fa 100644
--- a/openviking/config/binding.py
+++ b/openviking/config/binding.py
@@ -21,7 +21,11 @@ from openviking.config.source.file_source import FileConfigSource
from openviking.config.validate import validate_patch
from openviking.pyagfs import AsyncAGFSClient
from openviking_cli.utils.config import get_openviking_config, set_openviking_config
+from openviking_cli.utils.config.config_utils import warn_unknown_config_fields
from openviking_cli.utils.config.open_viking_config import OpenVikingConfig, RuntimeConfigSettings
+from openviking_cli.utils.logger import get_logger
+
+logger = get_logger(__name__)
# The concrete manager type this module hands back.
OpenVikingRuntimeConfigManager = RuntimeConfigManager[OpenVikingConfig, AccountConfig]
@@ -49,8 +53,16 @@ def _build_cluster(old: OpenVikingConfig, override: dict) -> OpenVikingConfig:
def _build_account(override: Optional[dict]) -> AccountConfig:
- """Construct (and thereby validate) an account config from its sparse override."""
- return AccountConfig.model_validate(override or {})
+ """Construct (and thereby validate) an account config from its sparse override.
+
+ A persisted account override may carry fields this binary does not declare --
+ a retired ``namespace`` block, or a section written by a newer binary. They
+ stay ignored so legacy settings keep loading, and the warning keeps the drop
+ visible. Only field names are logged, never values.
+ """
+ sparse = override or {}
+ warn_unknown_config_fields(data=sparse, model=AccountConfig, logger=logger)
+ return AccountConfig.model_validate(sparse)
def _validate_request(patch: dict, is_account: bool, creating: bool) -> None:
diff --git a/openviking/server/config.py b/openviking/server/config.py
index 99e2a7e2d..fa75c8eb9 100644
--- a/openviking/server/config.py
+++ b/openviking/server/config.py
@@ -18,7 +18,10 @@ from openviking_cli.utils.config.config_loader import (
load_json_config,
resolve_config_path,
)
-from openviking_cli.utils.config.config_utils import format_validation_error
+from openviking_cli.utils.config.config_utils import (
+ format_validation_error,
+ warn_unknown_config_fields,
+)
from openviking_cli.utils.config.consts import (
DEFAULT_CONFIG_DIR,
DEFAULT_OV_CONF,
@@ -479,6 +482,13 @@ def load_server_config(config_path: Optional[str] = None) -> ServerConfig:
"See documentation for more details."
)
+ warn_unknown_config_fields(
+ data=server_data,
+ model=ServerConfig,
+ path_prefix="server",
+ logger=logger,
+ )
+
try:
config = ServerConfig.model_validate(server_data)
except ValidationError as e:
diff --git a/openviking_cli/utils/config/config_utils.py b/openviking_cli/utils/config/config_utils.py
index 11251a02e..e2a4d2637 100644
--- a/openviking_cli/utils/config/config_utils.py
+++ b/openviking_cli/utils/config/config_utils.py
@@ -3,6 +3,8 @@
"""Shared helpers for config validation and error formatting."""
import difflib
+import logging
+from collections.abc import Mapping
from typing import Any, Optional, get_args, get_origin
from pydantic import BaseModel, ValidationError
@@ -46,6 +48,86 @@ def _get_model_at_path(
return current_model
+def warn_unknown_fields(
+ *,
+ data: Mapping[str, Any],
+ valid_fields: set[str],
+ logger: logging.Logger,
+ path_prefix: str = "",
+) -> None:
+ """Warn about keys the owner of one config section does not declare.
+
+ Unknown fields stay ignored so legacy configuration keeps loading; the
+ warning keeps the mismatch visible to whoever wrote the file. Only field
+ names are logged, never values.
+ """
+ messages = []
+ for key in data:
+ if key in valid_fields:
+ continue
+ field_path = f"{path_prefix}.{key}" if path_prefix else key
+ # Config files are JSON, but from_dict() is also called programmatically;
+ # a diagnostic must never be the reason loading fails.
+ messages.append(f"Ignoring unknown config field '{field_path!s}'")
+ if messages:
+ logger.warning("%s", "\n".join(messages))
+
+
+def _child_model_type(annotation: Any) -> Optional[type[BaseModel]]:
+ """Return the model nested values must validate against, when unambiguous."""
+ if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+ return annotation
+
+ args = get_args(annotation)
+ if not args or any(get_origin(arg) in (dict, Mapping) for arg in args):
+ return None
+
+ models = {model for model in (_unwrap_model_type(arg) for arg in args) if model is not None}
+ if len(models) == 1:
+ return models.pop()
+ return None
+
+
+def warn_unknown_config_fields(
+ *,
+ data: Mapping[str, Any],
+ model: type[BaseModel],
+ logger: logging.Logger,
+ path_prefix: str = "",
+ extra_valid_fields: Optional[set[str]] = None,
+) -> None:
+ """Warn about config keys the model does not declare, recursing into sub-models.
+
+ ``extra_valid_fields`` lists keys consumed by another owner (for example the
+ ``server`` section) so they are not reported as unknown.
+ """
+ warn_unknown_fields(
+ data=data,
+ valid_fields=set(model.model_fields) | (extra_valid_fields or set()),
+ logger=logger,
+ path_prefix=path_prefix,
+ )
+
+ for key, value in data.items():
+ field = model.model_fields.get(key)
+ if field is None:
+ continue
+ child_model = _child_model_type(field.annotation)
+ if child_model is None:
+ continue
+ child_prefix = f"{path_prefix}.{key}" if path_prefix else key
+ is_sequence = isinstance(value, (list, tuple))
+ for index, item in enumerate(value if is_sequence else (value,)):
+ if not isinstance(item, Mapping):
+ continue
+ warn_unknown_config_fields(
+ data=item,
+ model=child_model,
+ logger=logger,
+ path_prefix=f"{child_prefix}[{index}]" if is_sequence else child_prefix,
+ )
+
+
def format_validation_error(
*,
root_model: type[BaseModel],
diff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.py
index e8dbf082d..b418bc6fc 100644
--- a/openviking_cli/utils/config/open_viking_config.py
+++ b/openviking_cli/utils/config/open_viking_config.py
@@ -14,7 +14,11 @@ from openviking_cli.session.user_id import UserIdentifier
from .agent_evolution_config import AgentEvolutionConfig
from .cache_config import CacheConfig
from .config_loader import resolve_config_path
-from .config_utils import format_validation_error
+from .config_utils import (
+ format_validation_error,
+ warn_unknown_config_fields,
+ warn_unknown_fields,
+)
from .consts import (
DEFAULT_CONFIG_DIR,
DEFAULT_OV_CONF,
@@ -477,6 +481,13 @@ class OpenVikingConfig(BaseModel):
"webfeed",
]
+ warn_unknown_config_fields(
+ data=config_copy,
+ model=cls,
+ extra_valid_fields={"server", "bot", "parsers"},
+ logger=_get_config_logger(),
+ )
+
# Remove sections managed by other loaders (e.g. server config)
config_copy.pop("server", None)
config_copy.pop("bot", None)
@@ -496,6 +507,12 @@ class OpenVikingConfig(BaseModel):
"Config field 'parsers.excel' was removed and is ignored; "
"spreadsheet parsing now uses 'parsers.anydoc'."
)
+ warn_unknown_fields(
+ data=parser_configs,
+ valid_fields=set(parser_types),
+ path_prefix="parsers",
+ logger=_get_config_logger(),
+ )
for parser_type in parser_types:
if parser_type in config_copy:
parser_configs[parser_type] = config_copy.pop(parser_type)
@@ -534,6 +551,13 @@ class OpenVikingConfig(BaseModel):
if parser_type in parser_configs:
parser_data = parser_configs[parser_type]
config_class = getattr(instance, parser_type).__class__
+ if isinstance(parser_data, dict):
+ warn_unknown_fields(
+ data=parser_data,
+ valid_fields=set(config_class.__dataclass_fields__),
+ path_prefix=f"parsers.{parser_type}",
+ logger=_get_config_logger(),
+ )
setattr(instance, parser_type, config_class.from_dict(parser_data))
# Check dimension consistency
diff --git a/tests/test_config_loader.py b/tests/test_config_loader.py
index 132ad93c3..c6cefcce5 100644
--- a/tests/test_config_loader.py
+++ b/tests/test_config_loader.py
@@ -309,11 +309,14 @@ def test_openviking_config_handles_nested_parser_compatibility(monkeypatch):
OpenVikingConfigSingleton.reset_instance()
-def test_openviking_config_ignores_unknown_fields(monkeypatch):
+def test_openviking_config_ignores_unknown_fields(monkeypatch, caplog):
monkeypatch.setenv(OPENVIKING_CONFIG_ENV, "/tmp/codex-no-config.json")
+ logger = logging.getLogger("openviking_cli.utils.config.open_viking_config")
+ monkeypatch.setattr(logger, "handlers", [*logger.handlers, caplog.handler])
+ caplog.set_level(logging.WARNING, logger=logger.name)
config = OpenVikingConfig.from_dict(
{
- "retired_section": {"enabled": True},
+ "retired_section": {"api_key": "test-secret"},
"default_user": "alice",
"glob": {"retired_field": True, "engine": "fs"},
"memory": {"unknown_memory_field": "value", "session_skill_extraction_enabled": True},
@@ -339,6 +342,9 @@ def test_openviking_config_ignores_unknown_fields(monkeypatch):
assert "retired_field" not in dumped["glob"]
assert "unknown_memory_field" not in dumped["memory"]
assert "cache" not in dumped["storage"]["agfs"]
+ assert "Ignoring unknown config field 'storage.agfs.cache'" in caplog.text
+ assert "Ignoring unknown config field 'parsers.markdown.unknown_field'" in caplog.text
+ assert "test-secret" not in caplog.text
def test_memory_extraction_output_format_defaults_to_python_and_accepts_json(monkeypatch):