#2405·sd-scripts

--tag_replacement doesn't actually replace anything (variable shadowing bug)

Author: TSolo315Created Jul 19, 2026Updated Jul 25, 2026

--tag_replacement in finetune/tag_images_by_wd14_tagger.py does not actually replace any tags in the output captions, despite the log correctly printing replacing tag: X -> Y for each configured pair.

Ran into this while curating a dataset — set --tag_replacement "1girl,female;1boy,male" and the console log looks normal

But when I checked the actual .txt caption files afterward, the tags hadn't changed at all — still 1girl, 1boy, etc. Took a bit to figure out why since the log makes it look like it's working. Traced it to process_tag_replacement() in finetune/tag_images_by_wd14_tagger.py. The loop variable used to hold each parsed source,target pair is named tags, which is also the name of the function's parameter

python
def process_tag_replacement(tags: list[str], tag_replacements_arg: str) -> list[str]:
    ...
    for tag_replacements_arg in tag_replacements:
        tags = tag_replacements_arg.split(",")  # this stomps the tags param
        ...
        if source in tags:
            tags[tags.index(source)] = target
    return tags

Every iteration overwrites tags with a throwaway 2-item list ([source, target]), so the actual tag list passed in never gets touched.

fix (replace tag variable name):

python
def process_tag_replacement(tags: list[str], tag_replacements_arg: str) -> list[str]:
    escaped_tag_replacements = tag_replacements_arg.replace("\\,", "@@@@").replace("\\;", "####")
    tag_replacements = escaped_tag_replacements.split(";")
    for replacement_pair in tag_replacements:
        pair = replacement_pair.split(",")
        assert len(pair) == 2, f"tag replacement must be in the format of `source,target`: {tag_replacements_arg}"
        source, target = [tag.replace("@@@@", ",").replace("####", ";") for tag in pair]
        logger.info(f"replacing tag: {source} -> {target}")
        if source in tags:
            tags[tags.index(source)] = target
    return tags