[Bug]: netbox_prefix: documented vlan_group lookup key for vlan is silently ignored on NetBox 4.x (cannot disambiguate same-named VLANs by group) #1570

Ansible NetBox Collection version

v3.22.0

Ansible version

ansible-core 2.20.4, Python 3.12

NetBox version

v4.5.8

Python version

3.11

Steps to Reproduce

Notes

I've been having issues with this, tried to fix myself and Claude was able to help point me in the right direction.

Title

netbox_prefix: documented vlan_group lookup key for vlan is silently ignored on NetBox 4.x (cannot disambiguate same-named VLANs by group)

Component

plugins/modules/netbox_prefix.py (the vlan field lookup), plugins/module_utils/netbox_utils.py

Environment

• collection netbox.netbox 3.22.0
• NetBox 4.5.8
• ansible-core 2.20.4, Python 3.12

Summary

The netbox_prefix module documents disambiguating a VLAN association by its group, via the
vlan_group key in the vlan dict (see the module's own EXAMPLES):

vlan:
  name: Test VLAN
  site: Test Site
  vlan_group: Test Vlan Group

On NetBox 4.x this does not narrow the lookup. When two VLANs share a name (in different
groups/sites), the module fails with:

Module failed: More than one result returned for vlan

even though a vlan_group was provided to disambiguate.

Root cause (from inspecting netbox_utils.py)

When the vlan dict is resolved, the child keys map to query params for GET /api/ipam/vlans/:

1. vlan_group is in ALLOWED_QUERY_PARAMS["vlan"] but not in QUERY_PARAMS_IDS, so it is
   passed through verbatim as the query param vlan_group=<value>. The NetBox 4.x VLAN filterset
   has no vlan_group field — the real filters are group (slug) / group_id — so NetBox
   silently ignores it and returns all name matches.
2. The alternative key group is in QUERY_PARAMS_IDS, but CONVERT_TO_ID["group"] maps to
   the tenant_groups endpoint, so it tries to resolve the VLAN group name against tenant
   groups and can't find it.

Net effect: neither child key can disambiguate a VLAN by its VLAN group on NetBox 4.x.

Reproduction

Against NetBox 4.5.8, with two VLANs both named PRINTERS, one in VLAN group A and one in
group B:

# Real filter — works:
curl -s -H "Authorization: Token $T" "$U/api/ipam/vlans/?name=PRINTERS&group=a"        # -> count 1
# Documented module key — ignored, returns everything:
curl -s -H "Authorization: Token $T" "$U/api/ipam/vlans/?name=PRINTERS&vlan_group=a"    # -> count 2

Module-level repro:

- netbox.netbox.netbox_prefix:
    netbox_url: "{{ url }}"
    netbox_token: "{{ token }}"
    data:
      prefix: 10.0.8.0/24
      vlan:
        name: PRINTERS
        vlan_group: A      # ignored -> "More than one result returned for vlan"
    state: present

Secondary usability issue

When a scoping child key matches nothing (e.g. a site passed as a name when the module resolves
site by slug), the module silently drops the filter rather than erroring, so the failure
surfaces later as the confusing More than one result returned for vlan. A
"no match found for site=" style error would make this far easier to diagnose.

Workaround

Disambiguate by site instead — but note site is resolved by slug, so pass the lowercase
slug, not the display name:

vlan:
  name: "{{ vlan_prefix['name'] }}"
  site: "{{ site | lower }}"   # slug, e.g. sea-hqs (NOT SEA-HQS)

Expected Behavior

Expected

Either:

• the vlan_group child key resolves the VLAN group and queries with the supported
  group_id / group (slug) filter, or
• the EXAMPLES/docs stop advertising vlan_group as a disambiguator on NetBox 4.x.

Observed Behavior

[ERROR]: Task failed: Module failed: More than one result returned for vlan

52     - ipam_vlans
53
54 - name: Add VLAN prefixes
     ^ column 3

failed: [localhost] (item=10.0.8.0/24) => {"ansible_loop_var": "vlan_prefix", "changed": false, "msg": "More than one result returned for vlan", "vlan_prefix": {"name": "PRINTERS", "prefix": "10.0.8.0/24", "role": "User", "vid": 8}}