[HELP] UI Crash "Cannot read properties of null (reading 'map')" when using "Pick from Docker Containers"

[khannhub]

What happened?
When trying to create a new Proxy Rule, clicking the "Pick from Docker Containers" button causes the UI to fail and throws a JavaScript error in the browser console. The list of containers never renders.

The error in the console is:
TypeError: Cannot read properties of null (reading 'map') at processDockerData.

Describe what have you tried

1. Checked docker-socket-proxy permissions. I have verified that Zoraxy has full access to CONTAINERS, IMAGES, NETWORKS, etc.
2. Verified the backend API is working. A manual request to https://[zoraxy-url]/api/docker/containers returns a 200 OK and a valid JSON list of all my containers.
3. Compared environments: This setup works fine on my remote production server but crashes on my local development environment (Docker Desktop on macOS) using the exact same Compose configuration.

Technical Analysis (Potential Cause)
I investigated the JSON response from /api/docker/containers on the machine where it crashes.
Several containers (e.g., authentik-worker, cloudflared, those who don't have mapped ports to host, only have exposed ports to docker network) have "Ports": null instead of an empty array [].

JSON Response from /api/docker/containers endpoint

{
  "containers": [
    {
      "Id": "...",
      "Names": ["/authentik-worker"],
      "Image": "authentik/server:2025.10",
      "ImageID": "sha256:...",
      "Command": "dumb-init -- ak worker",
      "Created": "...",
      "Ports": null,
    }
  ]
}

Stack Trace:

jquery-3.6.0.min.js:2 TypeError: Cannot read properties of null (reading 'map')
    at <anonymous>:172:43
    at Array.forEach (<anonymous>)
    at processDockerData (<anonymous>:133:20)
    at getDockerContainers (<anonymous>:100:13)

Describe the networking setup you are using

• Are you using the docker build of Zoraxy? Yes
• Zoraxy version? zoraxydocker/zoraxy:v3.3.0 (Image ID: sha256:1d88ee9f6ded9db63757e8f9336c5715fc529496c7e8b0b3c17f7706f57e3a5a)
• Are you using Cloudflare? Yes (Cloudflared Tunnel)
• Host OS: macOS
  • Docker Desktop: 4.55.0
  • Docker Engine: 29.1.3
  • Docker Compose: v2.40.3-desktop.1
• Docker Socket Proxy: Zoraxy is running behind tecnativa/docker-socket-proxy with the following permissions enabled. Here is the docker-compose.yaml file:

environment:
  LOG_LEVEL: info
  INFO: 1
  PING: 1
  EVENTS: 1
  VERSION: 1
  NETWORKS: 1
  CONTAINERS: 1

Additional context
I suspect that the frontend processDockerData function assumes Ports is always an array and attempts to .map() it without checking if it is null first.

Here is the additional screenshot where the error pops up:

[tobychui]

I think I have seen something similar before, it should be cause by a docker settings related issue.
@PassiveLemon you got any clues on this?

[PassiveLemon]

Is this only present with a socket proxy? Also this seems like an issue for @eyerrock to figure out since theyre the one who implemented the pick-from-container feature

[eyerrock]

The linked PR should fix this by normalizing container.Ports to an empty array when Docker returns null, preventing runtime errors during iteration.

[khannhub]

Is this only present with a socket proxy?

Thanks for the suggestion 🙌. Unfortunately, the error still occured when I switched back to using host Docker socket mount. But I don't think it was related to the socket proxy though, as can still call the API when using the socket proxy.

    volumes:
      - zoraxy-config:/opt/zoraxy/config
      - zoraxy-plugins:/opt/zoraxy/plugin
      - ${ZORAXY_LOCALTIME_MOUNT:-/etc/localtime:/etc/localtime:ro}
      - ${ZORAXY_DOCKER_SOCK_MOUNT:-/var/run/docker.sock:/var/run/docker.sock:ro}

    environment:
      TZ: ${ZORAXY_TIMEZONE:-Etc/UTC}
      ZEROTIER: ${ZORAXY_ZEROTIER:-true}
      FASTGEOIP: ${ZORAXY_FASTGEOIP:-false}
      # DOCKER_HOST: tcp://${ZORAXY_SOCKET_PROXY_SERVICE_NAME:-zoraxy-socket-proxy}:${ZORAXY_SOCKET_PROXY_PORT:-2375}

[coaxk]

Root Cause Identified: I have successfully reproduced and isolated the crash. It is confirmed to be caused by the Docker API on Windows returning Ports: null for containers that do not have any exposed ports (Internal-only containers).

The Smoking Gun: I inspected the JSON payload returning from the API. My container plex-auto-languages had no ports mapped in compose.yaml, resulting in this JSON response:

JSON

"Names": ["/plex-auto-languages"],
"Ports": null
The Zoraxy frontend appears to attempt a .map() on this field without checking for null, causing the white-screen crash.

Confirmed Workaround: I added a dummy port mapping (9999:9999) to the container in question.

Docker immediately updated the JSON to return Ports: [{"PublicPort": 9999...}].

The Zoraxy dashboard loaded successfully with no errors.

Recommendation: A simple null-check in the frontend Javascript (e.g., (container.Ports || []).map(...)) should permanently resolve this for all Windows users.

[khannhub]

Root Cause Identified: I have successfully reproduced and isolated the crash. It is confirmed to be caused by the Docker API on Windows returning Ports: null for containers that do not have any exposed ports (Internal-only containers).

...

Recommendation: A simple null-check in the frontend Javascript (e.g., (container.Ports || []).map(...)) should permanently resolve this for all Windows users.

Actually, the bug seems to happen on macOS also (Mine is macOS Tahoe 26.2 on a Mac mini). I think this got something to do with Docker Engine being Linux-native, instead of mere virtualiztion on Windows and macOS. Something must have been lost during the layers of translation. With that being said, this is to be expected as it has been an annoying problem for developers for years. I thought I could get away with macOS (which is based on Unix). But looks like it still got way to go. Luckyly I still got my home server running on a Debian VM (Proxmox saves the day).

Cheers for the developers who are making our life better day by day!
Last but not least, Happy New Year to all of you!