ultralytics/ultralytics · error · TypeError

Ultralytics setting '{k}' must be '{t.name}' type, not '

Error message

Ultralytics setting '{k}' must be '{t.__name__}' type, not '{type(v).__name__}'. {self.help_msg}

What it means

Raised by SettingsManager.update when a key is valid but the value's Python type differs from the type of that key's default. Each settings key has a fixed expected type (bool for sync, str for api_key/dirs, etc.) and the manager enforces isinstance(v, type(defaults[k])) on every update.

Source

Thrown at ultralytics/utils/__init__.py:1475

                f"must be different than 'runs_dir: {self.get('runs_dir')}'. "
                f"Please change one to avoid possible issues during training. {self.help_msg}"
            )

    def __setitem__(self, key, value):
        """Update one key: value pair."""
        self.update({key: value})

    def update(self, *args, **kwargs):
        """Update settings, validating keys and types."""
        for arg in args:
            if isinstance(arg, dict):
                kwargs.update(arg)
        for k, v in kwargs.items():
            if k not in self.defaults:
                raise KeyError(f"No Ultralytics setting '{k}'. {self.help_msg}")
            t = type(self.defaults[k])
            if not isinstance(v, t):
                raise TypeError(
                    f"Ultralytics setting '{k}' must be '{t.__name__}' type, not '{type(v).__name__}'. {self.help_msg}"
                )
        super().update(*args, **kwargs)

    def reset(self):
        """Reset the settings to default and save them."""
        self.clear()
        self.update(self.defaults)


def deprecation_warn(arg, new_arg=None):
    """Issue a deprecation warning when a deprecated argument is used, suggesting an updated argument."""
    msg = f"'{arg}' is deprecated and will be removed in the future."
    if new_arg is not None:
        msg += f" Use '{new_arg}' instead."
    LOGGER.warning(msg)

View on GitHub (pinned to 0449ea011c)

Solutions

Coerce to the default's type before updating — check SETTINGS.defaults[k] for the expected type.
For booleans coming from CLI/env, parse first: value in {'true','1','yes'} style logic or argparse type=bool handling.
Run `yolo settings` to confirm the value stuck after fixing.

Example fix

# before
SETTINGS.update({"sync": "False"})  # str vs bool -> TypeError

# after
SETTINGS.update({"sync": False})

Defensive patterns

Strategy: validation

Validate before calling

from ultralytics.utils import SETTINGS

def typed_update(key, value):
    t = type(SETTINGS.defaults[key])  # KeyError here means bad key — handle separately
    SETTINGS.update({key: t(value)})  # e.g. t='bool' -> careful: bool('False') is True; parse explicitly below

# explicit bool parsing for strings:
def parse_bool(v):
    return v if isinstance(v, bool) else str(v).strip().lower() in {"1", "true", "yes"}

Type guard

def matches_setting_type(key, value) -> bool:
    from ultralytics.utils import SETTINGS
    return key in SETTINGS.defaults and isinstance(value, type(SETTINGS.defaults[key]))

Try / catch

try:
    SETTINGS.update({"sync": value})
except TypeError as e:
    raise TypeError(f"wrong type for sync: {e}") from e

Prevention

When forwarding CLI/env values into SETTINGS, convert strings to the default's type first (especially booleans: 'False' is truthy if you rely on bool()).
After scripted settings changes, run `yolo settings` to verify values took effect.

When it happens

Trigger: Passing a string where a bool is expected: `yolo settings sync=False` from a CLI script that hands the literal string 'False' to update; passing int for a str-typed key; passing a Path instead of str for datasets_dir.

Common situations: Wrapping the yolo CLI in shell scripts and forwarding untyped string arguments into SETTINGS.update; JSON-loaded settings where booleans arrive as strings; programmatic updates that skip coercion.

Related errors

AI-assisted analysis of ultralytics/ultralytics@0449ea011c (2026-08-15). Data as JSON: /api/errors/3bdcaf58c0060d1e. Report an issue: GitHub.