Repository navigation
ListImagesCmd#withImageNameFilter is not working anymore with Docker API 1.41+ #2557
Description
Hello,
we noticed recently a regression after upgrading the version of Docker in one of our machine related to a test using ListImagesCmd#withImageNameFilter to find if a docker image was locally present before creating it.
So, for example, I have locally an image named xwiki-tomcat-jre25-office:b372e3023b3b21630385b22e1b19c70eaef70364988917e6d27613341c951536, which also has a specific label "image-version": "LO-25.2.7". If I use the CLI to search for an image with a name containing a different hash such as:
docker images xwiki-tomcat-jre25-office:71af718ae80d90b93c3b3c36eb9b0cf9e102e845b260d1f1e33a07fbda511322 --filter "label=image-version=LO-25.2.7"
Then the command line properly returns no result.
However, when I use the following snippet using docker-java:
DockerClient dockerClient = DockerClientImpl.getInstance(config, httpClient);
List<Image> imageList = dockerClient.listImagesCmd()
.withImageNameFilter(
"xwiki-tomcat-jre25-office:71af718ae80d90b93c3b3c36eb9b0cf9e102e845b260d1f1e33a07fbda511322")
.withLabelFilter(Map.of("image-version", "LO-25.2.7"))
.exec();
I now obtain in the list one occurence, the image
xwiki-tomcat-jre25-office:b372e3023b3b21630385b22e1b19c70eaef70364988917e6d27613341c951536, while I'm expecting the list to be empty. And before the upgrade of the Docker packages on the machine, the list was empty.
After investigation this is apparently because docker-java performs the following request:
11:27:14.576 [main] TRACE o.t.s.c.g.d.c.exec.ListImagesCmdExec - GET: DefaultWebTarget{path=[/images/json], queryParams={filter=[xwiki-tomcat-jre25-office:71af718ae80d90b93c3b3c36eb9b0cf9e102e845b260d1f1e33a07fbda511322], filters=[{"label":["image-version=LO-25.2.7"]}]}}
You can note the presence of queryParams={filter=[xwiki-tomcat-jre25-office:71af718ae80d90b93c3b3c36eb9b0cf9e102e845b260d1f1e33a07fbda511322]. And apparently this filter query param has been removed from Docker API since version 1.41, see in release notes:
The filter (singular) query parameter, which was deprecated in favor of the filters option in Docker 1.13, has now been removed from the GET /images/json endpoint. The parameter remains available when using API version 1.40 or below.
So IMO the ListImagesCmd#withImageNameFilter API is now broken with recent versions of Docker API. Either it should be fixed, or at the very least it should be deprecated / some javadoc should be added to inform that it might not work as expected.
Activity
[Misc] Fix problem to detect presence of docker container LO image
[Misc] Fix problem to detect presence of docker container LO image
[Misc] Fix problem to detect presence of docker container LO image
[Misc] Fix problem to detect presence of docker container LO image
bluemeaford commentedon Dec 31, 2025
Thanks for reporting this — could you clarify which Docker daemon version and API version you’re using when withImageNameFilter fails?
Is the behavior different with earlier API versions? That would help determine whether this stems from a Docker API change or a client compatibility issue.
surli commentedon Jan 5, 2026
Well as I linked this is documented as a Docker API change in: https://docs.docker.com/reference/api/engine/version-history/#v141-api-changes so the breaking change appeared in Docker API 1.41.
I have locally:
and I reproduced the problem using com.github.docker-java:docker-java-core:3.3.6. I can confirm that it stopped working after an upgrade of the Docker engine on some machines but I don't have the specifics about the versions from which it was upgraded.
bluemeaford commentedon Jan 10, 2026
Thanks — agreed, this lines up with the Docker API 1.41 change removing the singular
filterparam.I’m taking a look at how
withImageNameFilteris currently building the request to see whether this should be adjusted or deprecated. I’ll follow up once I’ve had a closer look.Deprecate ListImagesCmd#withImageNameFilter