LDAP authentication not working with server error "format requires a mapping"

[deppiedave64]

Hey everyone,
I'm currently having some trouble setting up LDAP authentication for NetBox 4.6.1. I'm not sure if something is wrong with my config and was wondering if someone could maybe point me in the right direction.

I'm currently using the following config for testing:

In configuration.py:

REMOTE_AUTH_ENABLED = True
REMOTE_AUTH_BACKEND = 'netbox.authentication.LDAPBackend'
REMOTE_AUTH_HEADER = 'HTTP_REMOTE_USER'
REMOTE_AUTH_USER_FIRST_NAME = 'HTTP_REMOTE_USER_FIRST_NAME'
REMOTE_AUTH_USER_LAST_NAME = 'HTTP_REMOTE_USER_LAST_NAME'
REMOTE_AUTH_USER_EMAIL = 'HTTP_REMOTE_USER_EMAIL'
REMOTE_AUTH_AUTO_CREATE_USER = True
REMOTE_AUTH_DEFAULT_GROUPS = []
REMOTE_AUTH_DEFAULT_PERMISSIONS = {}

ldap_config.py (some parts of the DNs replaced with placeholders):

import ldap
from django_auth_ldap.config import LDAPSearch, GroupOfNamesType, PosixGroupType

# Server URI
AUTH_LDAP_SERVER_URI = "ldaps://<REDACTED>"

# The following may be needed if you are binding to Active Directory.
AUTH_LDAP_CONNECTION_OPTIONS = {
    ldap.OPT_REFERRALS: 0
}

# Set the DN and password for the NetBox service account.
AUTH_LDAP_BIND_DN = "<REDACTED>"
AUTH_LDAP_BIND_PASSWORD = "<REDACTED>"

# If a user's DN is producible from their username, we don't need to search.
AUTH_LDAP_USER_DN_TEMPLATE = "uid=%(user)s,ou=People,ou=unix,ou=idm,dc=company,dc=local"

# You can map user attributes to Django attributes as so.
AUTH_LDAP_USER_ATTR_MAP = {
    "first_name": "givenName",
    "last_name": "sn",
    "email": "mail"
}

# This search ought to return all groups to which the user belongs. django_auth_ldap uses this to determine group
# hierarchy.
AUTH_LDAP_GROUP_SEARCH = LDAPSearch("ou=Groups,ou=unix,ou=idm,dc=company,dc=local", ldap.SCOPE_SUBTREE,
                                    "(&(objectClass=posixGroup)(memberUid=%(user)s))")
AUTH_LDAP_GROUP_TYPE = PosixGroupType(name_attr="cn")

# Define a group required to login.
AUTH_LDAP_REQUIRE_GROUP = "cn=netbox-users,ou=Groups,ou=unix,ou=idm,dc=company,dc=local"

# Mirror LDAP group assignments.
AUTH_LDAP_MIRROR_GROUPS = ["cn=netbox-users,ou=Groups,ou=unix,ou=idm,dc=company,dc=local"]

# Define special user types using groups. Exercise great caution when assigning superuser status.
AUTH_LDAP_USER_FLAGS_BY_GROUP = {
    "is_active": "cn=netbox-users,ou=Groups,ou=unix,ou=idm,dc=company,dc=local",
    "is_staff": "cn=netbox-users,ou=Groups,ou=unix,ou=idm,dc=company,dc=local",
    "is_superuser": "cn=netbox-users,ou=Groups,ou=unix,ou=idm,dc=company,dc=local",
}

# For more granular permissions, we can map LDAP groups to Django groups.
# AUTH_LDAP_FIND_GROUP_PERMS = True

# Cache groups for one hour to reduce LDAP traffic
AUTH_LDAP_CACHE_TIMEOUT = 0

The problem is that whenever I try to log in using my LDAP user, I just get a server error with the message "<class 'TypeError'> format requires a mapping". This is what appears in the NetBox log:

2026-06-01 16:18:08,353 [INFO] django_auth_ldap: Populating Django user <REDACTED>
2026-06-01 16:18:08,372 [WARNING] django_auth_ldap: format requires a mapping while authenticating <REDACTED>
2026-06-01 16:18:08,597 [ERROR] django.request: Internal Server Error: /login/
Traceback (most recent call last):
  File "/opt/netbox/netbox/netbox/middleware.py", line 164, in __call__
    username = request.META[self.header]
               ~~~~~~~~~~~~^^^^^^^^^^^^^
KeyError: 'HTTP_REMOTE_USER'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/core/handlers/exception.py", line 55, in inner
    response = get_response(request)
               ^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/core/handlers/base.py", line 198, in _get_response
    response = wrapped_callback(request, *callback_args, **callback_kwargs)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/views/generic/base.py", line 106, in view
    return self.dispatch(request, *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/utils/decorators.py", line 48, in _wrapper
    return bound_method(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/views/decorators/debug.py", line 143, in sensitive_post_parameters_wrapper
    return view(request, *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/netbox/account/views.py", line 52, in dispatch
    return super().dispatch(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/views/generic/base.py", line 145, in dispatch
    return handler(request, *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/netbox/account/views.py", line 110, in post
    if form.is_valid():
       ^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/forms/forms.py", line 206, in is_valid
    return self.is_bound and not self.errors
                                 ^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/forms/forms.py", line 201, in errors
    self.full_clean()
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/forms/forms.py", line 338, in full_clean
    self._clean_form()
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/forms/forms.py", line 354, in _clean_form
    cleaned_data = self.clean()
                   ^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/views/decorators/debug.py", line 75, in sensitive_variables_wrapper
    return func(*func_args, **func_kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/contrib/auth/forms.py", line 349, in clean
    self.user_cache = authenticate(
                      ^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/views/decorators/debug.py", line 75, in sensitive_variables_wrapper
    return func(*func_args, **func_kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django/contrib/auth/__init__.py", line 114, in authenticate
    user = backend.authenticate(request, **credentials)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django_auth_ldap/backend.py", line 173, in authenticate
    user = self.authenticate_ldap_user(ldap_user, password)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django_auth_ldap/backend.py", line 231, in authenticate_ldap_user
    return ldap_user.authenticate(password)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django_auth_ldap/backend.py", line 375, in authenticate
    self._get_or_create_user()
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django_auth_ldap/backend.py", line 664, in _get_or_create_user
    self._mirror_groups()
  File "/opt/netbox/netbox/netbox/authentication/misc.py", line 34, in _mirror_groups
    target_group_names = frozenset(self._get_groups().get_group_names())
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django_auth_ldap/backend.py", line 949, in get_group_names
    group_infos = self._get_group_infos()
                  ^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django_auth_ldap/backend.py", line 996, in _get_group_infos
    self._group_infos = self._group_type.user_groups(
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django_auth_ldap/config.py", line 480, in user_groups
    groups = search.execute(ldap_user.connection)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/netbox/venv/lib64/python3.12/site-packages/django_auth_ldap/config.py", line 200, in execute
    filterstr = self.filterstr % filterargs
                ~~~~~~~~~~~~~~~^~~~~~~~~~~~
TypeError: format requires a mapping

I'm not really sure how to interpret that error. I did find a similar error described in #1242, but since in my case the problem occurs regardless of whether my user is in the superuser group, I'm not sure if the two problems are related.

One weird thing I noticed: If I comment out AUTH_LDAP_MIRROR_GROUPS and instead activate AUTH_LDAP_FIND_GROUP_PERMS, restart NetBox, then reverse the config change, restart NetBox again, and then reload the NetBox web page (with the server error), I am suddenly successfully logged in. However, my LDAP group is not replicated in NetBox, which, as I understood the documentation, was supposed to happen when I put it in AUTH_LDAP_MIRROR_GROUPS. Anyway, as soon as I log out, I cannot log in again; it only works this once. Not sure if this is relevant, but it seems like in general authentication is working; otherwise, I shouldn't be able to log in once. So my guess was it has something to do with group mappings, but I don't know what else to try. Does anyone have any ideas?

Thanks in advance for any advice you can give!
David

[zmaster7]

I think AUTH_LDAP_MIRROR_GROUPS wants a list of group names as opposed to the DN (auth-ldap-mirror-groups). So, in this case it would be:

AUTH_LDAP_MIRROR_GROUPS = ["netbox-users"]

[deppiedave64]

@zmaster7 thanks for the tip! Unfortunately, using the CN of the group instead did not change anything about the problem. However, this morning I noticed that after commenting out AUTH_LDAP_MIRROR_GROUPS and activating AUTH_LDAP_FIND_GROUP_PERMS, I could actually successfully log into NetBox. I actually don't understand why, because I swear it did not work yesterday, and I did not change anything else. Maybe there are some inconsistencies in my environment. Anyway, I'll keep an eye on it and mark this as answered for now, since it does seem to be working at the moment.

[deppiedave64]

Unfortunately, I have to reopen this discussion, as my original problem reappeared. While LDAP login is working for my account now for some reason, when I try any other accounts, I get the same error as before. I even waited a few days and tried again to see if the problem would magically solve itself, like it did with my account, but that was not the case. Does anyone know what the cause of this behavior could be?

[deppiedave64]

I noticed that the login works and the error does not occur when I deactivate both AUTH_LDAP_MIRROR_GROUPS and AUTH_LDAP_FIND_GROUP_PERMS. However, as far as I can see, this means I would have to handle all group assignments manually within NetBox. While our team is probably small enough to do this, I would much prefer the option to sync group memberships from LDAP…