Omada SDN Controller 6.2.x cannot retrieve clients with OMDSDNOPENAPI

[mhanline]

What installation are you running?

Production (netalertx) 📦

Is there an existing issue for this?

• I have searched the existing open and closed issues and I checked the docs https://docs.netalertx.com/

The issue occurs in the following browsers. Select at least 2.

• Firefox
• Chrome
• Edge
• Safari (unsupported) - PRs welcome
• N/A - This is an issue with the backend

Current Behavior

With Omada SDN controller 6.2.0.17, NetalertX cannot retrieve any clients via its API. It does populate devices however. Previous versions of Omada controller did not have this behvaiour.

Issue appears only with Omada SDN controller 6.2.0.17. Seems to be an API change that was introduced.

Expected Behavior

Clients should be populated in netalertX

Steps To Reproduce

1. Deploy Omada SDN controller 6.2.0.17

This has been reported by other projects, based on my searches. It appears that the client API request (/openapi/v1/omadacId/sites/siteid/clients) needs to move to the v2 Open API. I've confirmed this with a manual curl request.

curl -H 'Content-type:application/json' -H 'Authorization: AccessToken=AT-redacted' 'https://mycontroller.mikehanline.com:8043/openapi/v1/omadacld/sites/siteid/clients?page=1&pageSize=1000' | jq
{
  "errorCode": -1,
  "msg": "General error."
}

The same request to the devices path succeeds.

The relevant debug logs which appear to show this are as follows:

16:45:05 [OMDSDNOPENAPI] [V] Retrieving clients for site: 68ca-redacted-31cf870
16:45:06 [OMDSDNOPENAPI] [D] GET request to endpoint: /openapi/v1/2cea5ae845-redacted-cc/sites/68ca-redacted-31cf870/clients?page=1&pageSize=1000
16:45:06 [OMDSDNOPENAPI] [D] Generated headers: {'Content-type': 'application/json', 'Authorization': 'AccessToken=AT-REDACTED'}
Starting new HTTPS connection (1): mycontroller.mikehanline.com:8043
https://mycontroller.mikehanline.com:8043 "GET /openapi/v1/2cea5ae845-redacted-cc/sites/68ca-redacted-31cf870/clients?page=1&pageSize=1000 HTTP/1.1" 200 None
16:45:06 [OMDSDNOPENAPI] [V] GET request completed: /openapi/v1/2cea5ae845-redacted-cc/sites/68ca-redacted-31cf870/clients?page=1&pageSize=1000
16:45:06 [OMDSDNOPENAPI] [M] Failed to retrieve clients for site redactedSite

Please see:

• Home Assistant
• tplink-omada-api

Relevant app.conf settings

N/A

docker-compose.yml

services:
  netalertx:
    container_name: netalertx
    image: ghcr.io/netalertx/netalertx:latest
    network_mode: host
    read_only: true
    cap_drop:
      - ALL
    cap_add:
      - NET_ADMIN
      - NET_RAW
      - NET_BIND_SERVICE
      - CHOWN
      - SETUID
      - SETGID
    volumes:
      - type: volume
        source: netalertx_data
        target: /data
        read_only: false
      - type: bind
        source: /etc/localtime
        target: /etc/localtime
        read_only: true
      - /dnsmasq-location.leases/etc/dnsmasq/dhcp.leases
    tmpfs:
      - "/tmp:uid=${NETALERTX_UID:-20211},gid=${NETALERTX_GID:-20211},mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
    environment:
      LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0}
      PORT: ${PORT:-20211}
      GRAPHQL_PORT: ${GRAPHQL_PORT:-20212}
      SKIP_STARTUP_CHECKS: "host mode network.sh"
    mem_limit: 2048m
    mem_reservation: 1024m
    cpu_shares: 512
    pids_limit: 512
    logging:
      options:
        max-size: "10m"
        max-file: "3"
    restart: unless-stopped
volumes:

Debug or Trace enabled

• I have read and followed the steps in the wiki link above and provided the required debug logs and the log section covers the time when the issue occurs.

Relevant app.log section

16:45:02 [OMDSDNOPENAPI] [M] Starting execution, version 0.3
16:45:02 [OMDSDNOPENAPI] [V] Configuration options loaded
16:45:02 [OMDSDNOPENAPI] [D] Initializing OmadaAPI with provided options
16:45:02 [OMDSDNOPENAPI] [D] Initialized option 'host' with value: https://mycontroller.mikehanline.com:8043
16:45:02 [OMDSDNOPENAPI] [D] Initialized option 'omada_id' with value: 2cea5ae845-redacted-cc
16:45:02 [OMDSDNOPENAPI] [D] Initialized option 'client_id' with value: c8a60-redacted-caf8e83
16:45:02 [OMDSDNOPENAPI] [D] Initialized option 'client_secret' with value: 7b6a3794fc7648-redacted-06
16:45:02 [OMDSDNOPENAPI] [D] Initialized option 'verify_ssl' with value: True
16:45:02 [OMDSDNOPENAPI] [D] Initialized option 'page_size' with value: 1000
16:45:02 [OMDSDNOPENAPI] [D] Initialized option 'sites' with value: ['redactedSite']
16:45:02 [OMDSDNOPENAPI] [V] OmadaAPI initialized
16:45:02 [OMDSDNOPENAPI] [V] Starting authentication process
16:45:03 [OMDSDNOPENAPI] [D] POST request to endpoint: /openapi/authorize/token?grant_type=client_credentials
16:45:03 [OMDSDNOPENAPI] [D] Generated headers: {'Content-type': 'application/json'}
Starting new HTTPS connection (1): mycontroller.mikehanline.com:8043
https://mycontroller.mikehanline.com:8043 "POST /openapi/authorize/token?grant_type=client_credentials HTTP/1.1" 200 None
16:45:03 [OMDSDNOPENAPI] [V] POST request completed: /openapi/authorize/token?grant_type=client_credentials
16:45:03 [OMDSDNOPENAPI] [M] Successfully authenticated
16:45:03 [OMDSDNOPENAPI] [V] Starting site population process
16:45:04 [OMDSDNOPENAPI] [D] GET request to endpoint: /openapi/v1/2cea5ae845-redacted-cc/sites?page=1&pageSize=1000
16:45:04 [OMDSDNOPENAPI] [D] Generated headers: {'Content-type': 'application/json', 'Authorization': 'AccessToken=AT-REDACTED'}
Starting new HTTPS connection (1): mycontroller.mikehanline.com:8043
https://mycontroller.mikehanline.com:8043 "GET /openapi/v1/2cea5ae845-redacted-cc/sites?page=1&pageSize=1000 HTTP/1.1" 200 None
16:45:04 [OMDSDNOPENAPI] [V] GET request completed: /openapi/v1/2cea5ae845-redacted-cc/sites?page=1&pageSize=1000
16:45:04 [OMDSDNOPENAPI] [D] Retrieved 1 sites in total
16:45:04 [OMDSDNOPENAPI] [D] Available sites: {'68ca-redacted-31cf870': 'redactedSite'}
16:45:04 [OMDSDNOPENAPI] [D] Active sites after filtering: {'68ca-redacted-31cf870': 'redactedSite'}
16:45:04 [OMDSDNOPENAPI] [M] Successfully populated 1 site(s)
16:45:04 [OMDSDNOPENAPI] [V] Requested sites: ['redactedSite']
16:45:04 [OMDSDNOPENAPI] [V] Available sites: {'68ca-redacted-31cf870': 'redactedSite'}
16:45:04 [OMDSDNOPENAPI] [V] Active sites: {'68ca-redacted-31cf870': 'redactedSite'}
16:45:04 [OMDSDNOPENAPI] [M] Starting data collection process
16:45:04 [OMDSDNOPENAPI] [V] Processing site: redactedSite (68ca-redacted-31cf870)
16:45:04 [OMDSDNOPENAPI] [V] Retrieving devices for site: 68ca-redacted-31cf870
16:45:05 [OMDSDNOPENAPI] [D] GET request to endpoint: /openapi/v1/2cea5ae845-redacted-cc/sites/68ca-redacted-31cf870/devices?page=1&pageSize=1000
16:45:05 [OMDSDNOPENAPI] [D] Generated headers: {'Content-type': 'application/json', 'Authorization': 'AccessToken=AT-REDACTED'}
Starting new HTTPS connection (1): mycontroller.mikehanline.com:8043
https://mycontroller.mikehanline.com:8043 "GET /openapi/v1/2cea5ae845-redacted-cc/sites/68ca-redacted-31cf870/devices?page=1&pageSize=1000 HTTP/1.1" 200 None
16:45:05 [OMDSDNOPENAPI] [V] GET request completed: /openapi/v1/2cea5ae845-redacted-cc/sites/68ca-redacted-31cf870/devices?page=1&pageSize=1000
16:45:05 [OMDSDNOPENAPI] [D] Retrieved 3 device(s) from site: redactedSite
16:45:05 [OMDSDNOPENAPI] [V] Starting normalization of 3 device(s) from site: redactedSite
16:45:05 [OMDSDNOPENAPI] [D] Normalized MAC address from 50-91-E3-1F-82-FD to 50:91:e3:1f:82:fd
16:45:05 [OMDSDNOPENAPI] [D] Converted timestamp 1775544276045 to datetime 2026-04-07 16:44:36 with timezone Australia/Sydney
16:45:05 [OMDSDNOPENAPI] [V] Failed to normalize MAC address 'None' - error: Value 'None' is not a valid MAC address
16:45:05 [OMDSDNOPENAPI] [D] Processed device entry: {'mac_address': '50:91:e3:1f:82:fd', 'ip_address': '100.65.90.6', 'name': 'sw-l1-cupb01', 'last_seen': '2026-04-07 16:44:36', 'site_name': 'redactedSite', 'parent_node_mac_address': '', 'parent_node_port': '', 'parent_node_ssid': '', 'vlan_id': '', 'device_type': 'switch'}
16:45:05 [OMDSDNOPENAPI] [D] Normalized MAC address from E4-FA-C4-BD-1D-DA to e4:fa:c4:bd:1d:da
16:45:05 [OMDSDNOPENAPI] [D] Converted timestamp 1775544291104 to datetime 2026-04-07 16:44:51 with timezone Australia/Sydney
16:45:05 [OMDSDNOPENAPI] [V] Failed to normalize MAC address 'None' - error: Value 'None' is not a valid MAC address
16:45:05 [OMDSDNOPENAPI] [D] Processed device entry: {'mac_address': 'e4:fa:c4:bd:1d:da', 'ip_address': '100.65.90.21', 'name': 'ap-gnd-hall01', 'last_seen': '2026-04-07 16:44:51', 'site_name': 'redactedSite', 'parent_node_mac_address': '', 'parent_node_port': '', 'parent_node_ssid': '', 'vlan_id': '', 'device_type': 'ap'}
16:45:05 [OMDSDNOPENAPI] [D] Normalized MAC address from 9C-A2-F4-43-D7-D4 to 9c:a2:f4:43:d7:d4
16:45:05 [OMDSDNOPENAPI] [D] Converted timestamp 1775544286587 to datetime 2026-04-07 16:44:46 with timezone Australia/Sydney
16:45:05 [OMDSDNOPENAPI] [V] Failed to normalize MAC address 'None' - error: Value 'None' is not a valid MAC address
16:45:05 [OMDSDNOPENAPI] [D] Processed device entry: {'mac_address': '9c:a2:f4:43:d7:d4', 'ip_address': '100.65.90.20', 'name': 'ap-gnd-kitch01', 'last_seen': '2026-04-07 16:44:46', 'site_name': 'redactedSite', 'parent_node_mac_address': '', 'parent_node_port': '', 'parent_node_ssid': '', 'vlan_id': '', 'device_type': 'ap'}
16:45:05 [OMDSDNOPENAPI] [M] Successfully normalized 3 device(s) from site: redactedSite
16:45:05 [OMDSDNOPENAPI] [V] Making entry for: 50:91:e3:1f:82:fd
16:45:05 [OMDSDNOPENAPI] [V] Making entry for: e4:fa:c4:bd:1d:da
16:45:05 [OMDSDNOPENAPI] [V] Making entry for: 9c:a2:f4:43:d7:d4
16:45:05 [OMDSDNOPENAPI] [V] Retrieving clients for site: 68ca-redacted-31cf870
16:45:06 [OMDSDNOPENAPI] [D] GET request to endpoint: /openapi/v1/2cea5ae845-redacted-cc/sites/68ca-redacted-31cf870/clients?page=1&pageSize=1000
16:45:06 [OMDSDNOPENAPI] [D] Generated headers: {'Content-type': 'application/json', 'Authorization': 'AccessToken=AT-REDACTED'}
Starting new HTTPS connection (1): mycontroller.mikehanline.com:8043
https://mycontroller.mikehanline.com:8043 "GET /openapi/v1/2cea5ae845-redacted-cc/sites/68ca-redacted-31cf870/clients?page=1&pageSize=1000 HTTP/1.1" 200 None
16:45:06 [OMDSDNOPENAPI] [V] GET request completed: /openapi/v1/2cea5ae845-redacted-cc/sites/68ca-redacted-31cf870/clients?page=1&pageSize=1000
16:45:06 [OMDSDNOPENAPI] [M] Failed to retrieve clients for site redactedSite

Docker Logs

  Not relevant

[jokob-sk]

Hi @mhanline ,

Thanks for the report. Pinging @xfilo if he has time to have a look.

This is a community created plugin (I don't own the required HW for testing), so fixes may take some time. I rely on the community for support in this area. If you're interested, feel free to take a look and submit a PR—collaboration is always welcome!

If you decide to help, feel free to check the following resources:

• Setting up your development environment
• Plugins Development + Video
• Discord development channels

[jokob-sk]

Also - thanks a lot for such a detailed issue description - this will help speed this up I hope.

[xfilo]

Hi,

I’ll definitely take a look at the issue, but I don’t have the capacity to dive into it right now. I expect to be able to investigate it in roughly two weeks.

[jokob-sk]

Hi @xfilo - thats understandable and no rush - I always appreciate the help