improve error messages for common config mistakes

This covers the main confusing cases: missing required key, bad module
paths, and malformed CLI overrides like `key` without `=`.

Unused config keys now produce direct JaQMC errors instead of a generic
stop or mixed raw exceptions.

Author: AllanChain

pyproject.toml

@@ -36,7 +36,7 @@ dependencies = [
     "jax>=0.4.36,<=0.9.1",
     "kfac-jax==0.0.8",
     "numpy>=2.3.5",
-    "pyserde>=0.31.1",
+    "pyserde>=0.31.7",
     "optax>=0.2.5",
     "pygments>=2.19.2",
     "pyscf>=2.11.0",

requirements.txt

@@ -181,7 +181,7 @@ pygments==2.20.0
     #   rich
 pyscf==2.12.1
     # via jaqmc
-pyserde==0.31.2
+pyserde==0.31.7
     # via jaqmc
 pytest==9.0.3
     # via

src/jaqmc/utils/cli.py

@@ -6,7 +6,7 @@
 import click
 import yaml
 
-from jaqmc.utils.config import ConfigManager
+from jaqmc.utils.config import ConfigError, ConfigManager
 from jaqmc.utils.runtime import configure_runtime
 
 
@@ -34,9 +34,12 @@ def make_cli(workflow=None, **kwargs):
     def command(
         dotlist: tuple[str, ...], yml: Sequence[str], dry_run: bool = False
     ) -> None:
-        cfg = ConfigManager([load_yaml(f) for f in yml], list(dotlist))
-        configure_runtime(cfg, dry_run=dry_run)
-        workflow(cfg, dry_run=dry_run)
+        try:
+            cfg = ConfigManager([load_yaml(f) for f in yml], list(dotlist))
+            configure_runtime(cfg, dry_run=dry_run)
+            workflow(cfg, dry_run=dry_run)
+        except ConfigError as e:
+            raise click.ClickException(str(e)) from None
 
     return command
 
@@ -51,11 +54,14 @@ def load_yaml(f):
         Plain dictionary config.
 
     Raises:
-        ValueError: YAML contains list config.
+        ConfigError: YAML root is not a mapping.
     """
+    source = getattr(f, "name", "<stream>")
     config = yaml.safe_load(f)
     if not isinstance(config, dict):
-        raise ValueError(
-            f"JaQMC expects a dictionary config from {f.read()}. Got {type(config)}."
+        got = "empty document" if config is None else type(config).__name__
+        raise ConfigError(
+            f"Invalid YAML config in '{source}': expected a mapping at the "
+            f"document root, got {got}."
         )
     return config

src/jaqmc/utils/config.py

@@ -17,7 +17,7 @@
 from pygments.lexers import DiffLexer, YamlLexer
 from serde.core import field as serde_field
 
-from jaqmc.utils.module_resolver import resolve_object
+from jaqmc.utils.module_resolver import ModuleResolutionError, resolve_object
 from jaqmc.utils.wiring import wire
 from jaqmc.utils.yaml_format import annotate_yaml_with_sources, dump_yaml
 
@@ -27,6 +27,11 @@
     logging.getLogger(__name__), extra={"category": "config"}
 )
 
+
+class ConfigError(ValueError):
+    """Raised when JaQMC configuration is invalid."""
+
+
 # =============================================================================
 # Public API: Decorators and field helpers
 # =============================================================================
@@ -412,14 +417,14 @@ def finalize(
         any unused configuration keys.
 
         Args:
-            raise_on_unused: If True, raises `SystemExit` if there are any
+            raise_on_unused: If True, raises :class:`ConfigError` if there are any
                 unused configuration keys in the input.
             verbose: If True, includes docstrings and source information in
                 the logged YAML output.
             compare_yaml: YAML from previous from to log the difference.
 
         Raises:
-            SystemExit: If `raise_on_unused` is True and unused keys are found.
+            ConfigError: If `raise_on_unused` is True and unused keys are found.
         """
         yaml_content = self.to_yaml(verbose=verbose)
         logger.info(
@@ -430,22 +435,28 @@ def finalize(
         )
         unused_yaml = _find_unused_yaml_path(self._visited_paths, self._user_config)
         unused_cli = _find_unused_yaml_path(self._visited_paths, self._cli_config)
-        if unused_yaml:
+        if (unused_yaml or unused_cli) and raise_on_unused:
+            lines = ["Unused config keys detected:"]
+            if unused_yaml:
+                lines.append(f"- from YAML/API: {unused_yaml}")
+            if unused_cli:
+                lines.append(f"- from CLI: {unused_cli}")
+            lines.append(
+                "\nRemove these keys, or set `workflow.config.ignore_extra=true` to "
+                "ignore extra config. If you call `cfg.finalize()` manually, use "
+                "`raise_on_unused=False`."
+            )
+            raise ConfigError("\n".join(lines))
+        elif unused_yaml:
             logger.warning(
                 "The following configs are specified via YAML/API but not used: %s",
                 sorted(unused_yaml),
             )
-        if unused_cli:
+        elif unused_cli:
             logger.warning(
                 "The following configs are specified via CLI but not used: %s",
                 sorted(unused_cli),
             )
-        if (unused_yaml or unused_cli) and raise_on_unused:
-            raise SystemExit(
-                "Stopping due to invalid configs specified. Please consider using "
-                "`raise_on_unused=False` if you are calling `cfg.finalize` manually, "
-                "or pass workflow.config.ignore_extra=True if you are using CLI."
-            )
         if compare_yaml is not None:
             diff = "\n".join(
                 difflib.unified_diff(
@@ -492,7 +503,9 @@ def get_module(self, name: str, default_module: str | Callable | type = ""):
                 else default_module[: default_module.rfind(".")]
             )
             module_name = self._get_primitive(f"{name}.module", default_module)
-            make_module = resolve_object(module_name, package=module_base)
+            make_module = self._resolve_config_module(
+                f"{name}.module", module_name, package=module_base
+            )
         else:
             default_module_name = (
                 f"{default_module.__module__}:{default_module.__name__}"
@@ -504,7 +517,9 @@ def get_module(self, name: str, default_module: str | Callable | type = ""):
             )
             module_name = self._get_primitive(f"{name}.module", default_module_name)
             if module_name != default_module_name:
-                make_module = resolve_object(module_name, package=module_base)
+                make_module = self._resolve_config_module(
+                    f"{name}.module", module_name, package=module_base
+                )
             else:
                 make_module = default_module
         if is_dataclass(make_module):
@@ -530,8 +545,15 @@ def get_collection(
         for k, v in module_configs.items():
             if v is None:
                 continue
+            if not isinstance(v, dict):
+                raise ConfigError(
+                    f"Invalid config at '{name}.{k}': expected a mapping, "
+                    f"got {type(v).__name__}."
+                )
+            if "module" not in v:
+                raise ConfigError(f"Missing required config key '{name}.{k}.module'.")
             module_path = v["module"]
-            make_module = resolve_object(module_path)
+            make_module = self._resolve_config_module(f"{name}.{k}.module", module_path)
             if is_dataclass(make_module):
                 default_item = default_dict.get(k, {})
                 default_config = {
@@ -635,6 +657,11 @@ def _get_dataclass[DataclassT](
         base_config = serde.to_dict(default) if not inspect.isclass(default) else {}
 
         config_data = user_config if user_config is not _MISSING else {}
+        if user_config is not _MISSING and not isinstance(config_data, dict):
+            raise ConfigError(
+                f"Invalid config at '{name}': expected a mapping, "
+                f"got {type(config_data).__name__}."
+            )
         if isinstance(config_data, dict):
             config_data = {k: v for k, v in config_data.items() if k != "module"}
         else:
@@ -644,7 +671,7 @@ def _get_dataclass[DataclassT](
         try:
             result = serde.from_dict(cls, merged)
         except serde.SerdeError as e:
-            raise serde.SerdeError(f"Invalid config at '{name}': {e}") from None
+            raise ConfigError(f"Invalid config at '{name}': {e}") from None
 
         if not inspect.isclass(default):
             _copy_runtime_fields(default, result)
@@ -656,6 +683,18 @@ def _get_dataclass[DataclassT](
 
         return cast(DataclassT, result)
 
+    def _resolve_config_module(
+        self,
+        path: str,
+        module_name: str,
+        *,
+        package: str | None = None,
+    ) -> Any:
+        try:
+            return resolve_object(module_name, package=package)
+        except ModuleResolutionError as e:
+            raise ConfigError(f"Invalid config at '{path}': {e}") from None
+
     def _get_callable[CallableT: Callable](
         self,
         name: str,
@@ -717,7 +756,13 @@ def _get_path(data: dict[str, Any], path: list[str], default: Any = None) -> Any
 def _dotlist_to_dict(dotlist: list[str]) -> dict[str, Any]:
     result: dict[str, Any] = {}
     for entry in dotlist:
+        if "=" not in entry:
+            raise ConfigError(
+                f"Invalid CLI override '{entry}': expected the form key=value."
+            )
         key, _, raw_value = entry.partition("=")
+        if not key:
+            raise ConfigError(f"Invalid CLI override '{entry}': key must not be empty.")
         _set_path(result, key, yaml.safe_load(raw_value))
     return result