invoke-ai/InvokeAI · error

Unknown image subfolder strategy: {strategy}

Error message

Unknown image subfolder strategy: {strategy}

What it means

_get_new_subfolder maps a MoveJobStrategy to a destination subfolder layout. If the strategy string is not one of the supported values (e.g. 'category', 'hash', 'date', 'none'/'intermediate' handling), the code raises ValueError('Unknown image subfolder strategy: {strategy}'). It is a configuration-validation error.

Source

Thrown at invokeai/app/services/image_moves/image_moves_default.py:745

            return None
        return ImageMoveJob(
            id=cast(int, row["id"]), state=cast(MoveJobState, row["state"]), error_message=row["error_message"]
        )

    def _get_new_subfolder(
        self, image_name: str, image_category: ImageCategory, is_intermediate: bool, created_at: str | datetime
    ) -> str:
        strategy = self._config.image_subfolder_strategy
        if strategy == "flat":
            return ""
        if strategy == "type":
            return "intermediate" if is_intermediate else image_category.value
        if strategy == "hash":
            return image_name[:2]
        if strategy == "date":
            timestamp = created_at if isinstance(created_at, datetime) else datetime.fromisoformat(created_at)
            return f"{timestamp.year}/{timestamp.month:02d}/{timestamp.day:02d}"
        raise ValueError(f"Unknown image subfolder strategy: {strategy}")

    def _get_items(self, job_id: int, include_terminal: bool = True) -> list[PlannedImageMove]:
        with self._db.transaction() as cursor:
            query = """--sql
                SELECT image_name, old_subfolder, new_subfolder, is_intermediate
                FROM image_subfolder_move_items
                WHERE job_id = ?
            """
            params: tuple[object, ...] = (job_id,)
            if not include_terminal:
                query += " AND state NOT IN ('committed', 'error')"
            query += " ORDER BY image_name;"
            cursor.execute(query, params)
            rows = cursor.fetchall()
        return [
            PlannedImageMove(
                image_name=row["image_name"],
                old_subfolder=row["old_subfolder"],

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Use exactly one of the supported strategies as defined by MoveJobStrategy (e.g. 'category', 'hash', 'date').
2. Check the MoveJobStrategy enum/type in the installed InvokeAI version and match casing/spelling.
3. If migrating from an older version, map deprecated strategy names to their new equivalents before calling.
4. Add validation at the config load site so invalid strategies fail fast with a clear message.

Example fix

// before
service.count_images_needing_move(strategy="folders")  # ValueError
// after
service.count_images_needing_move(strategy="category")  # supported strategy

SUPPORTED = {'category', 'hash', 'date'}
def strategy_is_valid(strategy: str) -> bool:
    return strategy in SUPPORTED
assert strategy_is_valid(cfg.strategy), f"unknown strategy {cfg.strategy!r}"

from typing import Literal
Strategy = Literal['category', 'hash', 'date']
def is_strategy(v: str) -> TypeGuard[Strategy]:
    return v in ('category', 'hash', 'date')

try:
    service.count_images_needing_move(strategy=strategy)
except ValueError as e:
    if "Unknown image subfolder strategy" in str(e):
        strategy = 'category'  # safe default

When it happens

Trigger: Calling count_images_needing_move or _plan_batch (via move_all_images) with a strategy value outside the supported set — typically a typo ('categeory'), a different-cased value ('Category'), or a strategy string from an older/newer API version.

Common situations: Config file or API payload using an unsupported/renamed strategy; hand-written scripts passing a strategy name guessed from docs; version upgrade renaming strategy enum values.

Understand the failure class

Background: "Invalid configuration value" and "Unsupported/Unknown setting value" errors: why libraries reject your config strings, numbers, and types — this error's family across 30 libraries.

Related errors

• {noise_type} noise width and height must be a multiple of {m
• Unsupported noise type: {noise_type}
• Unknown subfolder strategy: {strategy_name}. Valid options:
• Cannot create an image move job with no items
• Old and new paths are identical for {move.image_name}

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