[Bug]: UPnP fails on most routers, and discovery can flood the log

Open
  • Is something wrong?
#6,236 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
52/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
java
Domain
backend, networking

Research direction

The report names UPnPUtil for the MapTool changes and describes a separate fallback bug in upnplib's InternetGatewayDevice. Start by tracing UPnP interface discovery in UPnPUtil and how it invokes the library's listener; check the existing tests for those paths. Done means IPv6-only interfaces are skipped and sequential searches do not flood logs, with the gateway fallback handled in upnplib.

Written by the indexing model from the issue text.

Description

Describe the Bug

UPnP port mapping has three problems. The first means it fails on most home routers.

1. Ordinary routers aren't recognised (upnplib 1.2.0). upnplib 1.2.0 added support for version 2 gateways (upnplib PR #9, for #5123). InternetGatewayDevice now looks for WANIPConnection:2 first and is meant to fall back to :1, but the fallback checks the wrong variable:

UPNPService wanIPSrv = myIGDWANConnDevice.getService("urn:schemas-upnp-org:service:WANIPConnection:2");
if (myIGDWANConnDevice == null) {   // should be wanIPSrv == null
    ...
    wanIPSrv = myIGDWANConnDevice.getService("urn:schemas-upnp-org:service:WANIPConnection:1");
}

myIGDWANConnDevice can't be null there, so the fallback never runs. A router that offers WANIPConnection:1 and no WANPPPConnection is rejected without a message, and MapTool reports 0 gateways. That's the most common setup there is: my ASUS router describes InternetGatewayDevice:1 → WANConnectionDevice:1 → WANIPConnection:1. This affects every MapTool release that ships upnplib 1.2.0, in the client as well as the server.

2. Discovery can flood the log. MapTool searches each network interface in turn. For each search, upnplib's DiscoveryListener starts a listening thread. The thread keeps its socket in a shared field and is told to stop through a shared flag, which it only checks when the socket times out, every 250 ms. The next search starts within milliseconds, replaces the socket and raises the flag again, so the old thread carries on. When one thread finally exits, it closes the socket the other is still reading, and that thread then fails on every read without pausing, logging each failure. On a machine with Docker's virtual interfaces, two of three runs logged 332,401 and 439,777 copies of IO Exception during UPNP DiscoveryListener messages listening thread (285 and 377 MB) in about 20 seconds. Any PC with several network adapters (VPNs, Hyper-V, VirtualBox) could see the same.

3. Start-up waits on interfaces it can't search. upnplib only sends its search from IPv4 addresses, but it still waits out the whole discovery timeout on every interface it's given, including ones with only IPv6 addresses. Docker creates one of those per container. This is a remaining case of #4902.

To Reproduce
  1. Use a router that offers WANIPConnection:1 (most home routers).
  2. Start a server with UPnP on.
  3. The log says no gateways were found, and no port is mapped.

For 2 and 3, start the server with UPnP on a machine with several network interfaces, for example one running Docker.

Expected Behaviour
  1. The router is found and the port is mapped.
  2. Discovery logs no errors.
  3. Interfaces with no IPv4 address are skipped.
MapTool Info

develop (62b6b4a3c), upnplib 1.2.0

Desktop

Ubuntu 24.04 LTS (dedicated server), ASUS router

Additional Context

I tested fixes for all three on 2026-11-03, with a copy of upnplib patched for problem 1:

  • Problem 1: with the fix, the server logged Found IGD: ASUS Wireless Router and Port 51243 mapped. The router showed the mapping while the server ran, and it was gone after a normal stop.
  • Problem 2: waiting half a second after each interface, so each listening thread exits before the next search starts, gave three runs with no errors.
  • Problem 3: skipping interfaces with no IPv4 address took start-up from 83 seconds to 30.

The router answered the search twice, so MapTool counted it as two gateways and mapped the port twice. That's harmless, since it's one mapping, but worth knowing.

I'll open a PR to RPTools/upnplib for problem 1. The proper fix for problem 2 also belongs in upnplib: each listening thread should have its own socket and its own stop signal. Meanwhile I'll open a MapTool PR for 2 and 3, which only change UPnPUtil. Once upnplib has a release with the fix, MapTool needs a version bump.

#4049 ("UPnP scanning never finishes") might be problem 2, but I can't tell from the report.

Since problem 1 affects released versions, the fix may be worth a 1.19 backport.

Dominant language
Java
Stars
927
Forks
286
Avg merge
3d 17h
Merged PRs (30d)
94

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from RPTools/maptool

All issues in RPTools/maptool

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.