invoke-ai/InvokeAI · error

Unknown subfolder strategy: {strategy_name}. Valid options:

Error message

Unknown subfolder strategy: {strategy_name}. Valid options: {', '.join(strategies.keys())}

What it means

create_subfolder_strategy looks up the strategy name in a fixed registry ('none', 'date', 'type', 'hash'); unknown names raise ValueError listing valid options. This guards the runtime-configurable subfolder strategy setting.

Source

Thrown at invokeai/app/services/image_files/image_subfolder_strategy.py:57

class HashStrategy(ImageSubfolderStrategy):
    """Organize images by UUID prefix for filesystem performance (first 2 characters)."""

    def get_subfolder(self, image_name: str, image_category: ImageCategory, is_intermediate: bool) -> str:
        return image_name[:2]


def create_subfolder_strategy(strategy_name: str) -> ImageSubfolderStrategy:
    """Factory function to create a subfolder strategy by name."""
    strategies: dict[str, type[ImageSubfolderStrategy]] = {
        "flat": FlatStrategy,
        "date": DateStrategy,
        "type": TypeStrategy,
        "hash": HashStrategy,
    }
    cls = strategies.get(strategy_name)
    if cls is None:
        raise ValueError(f"Unknown subfolder strategy: {strategy_name}. Valid options: {', '.join(strategies.keys())}")
    return cls()

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Use one of the listed valid names: 'none', 'date', 'type', 'hash'
2. Lowercase and strip the configured value before passing it in
3. Update the config to the current version's supported strategy names

Example fix

// before
create_subfolder_strategy('Date')
// after
create_subfolder_strategy(config_value.strip().lower())  # 'date'

VALID_STRATEGIES = {'none', 'date', 'type', 'hash'}
def strategy_is_valid(cfg: str) -> bool:
    return cfg.strip().lower() in VALID_STRATEGIES
assert strategy_is_valid(config.images.subfolder_strategy)

def is_valid_strategy(v: object) -> bool:
    return isinstance(v, str) and v.strip().lower() in {'none', 'date', 'type', 'hash'}

try:
    strategy = create_subfolder_strategy(config.images.subfolder_strategy)
except ValueError as e:
    logger.error('%s — falling back to none', e)
    strategy = create_subfolder_strategy('none')

When it happens

Trigger: Calling ImageSubfolderStrategyFactory.create (or create_subfolder_strategy) with a misspelled or unsupported name, e.g. 'Date', 'dates', or 'none ' with whitespace; loading an old config value removed in a newer version.

Common situations: Typo in config file (images.subfolder_strategy); case mismatch ('Date' vs 'date'); config written for a version whose strategy set differs.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• {noise_type} noise width and height must be a multiple of {m
• Unsupported noise type: {noise_type}
• Unknown image subfolder strategy: {strategy}
• guidance_schedule has length {len(self.guidance_schedule)},
• No external provider config fields provided

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/900ce98606a3dbb6. Report an issue: GitHub.