filters: accept Docker-compat status values "dead" and "restarting" by crawfordxx · Pull Request #28926 · podman-container-tools/podman

crawfordxx · 2026-06-13T04:14:36Z

What did you do?

The GET /libpod/containers/json API documents dead and restarting as valid status filter values (matching Docker's API contract), but passing either causes a 500 error:

{"cause":"invalid argument","message":"unknown container state: dead: invalid argument","response":500}

What did you expect to happen?

status=dead and status=restarting should be accepted without error (returning an empty list, since Podman has no such internal states).

What actually happened?

StringToContainerStatus rejects them as unknown, bubbling up a 500.

How to reproduce it (as minimally and precisely as possible)?

curl --unix-socket /run/user/1000/podman/podman.sock \
  'http://d/v5/libpod/containers/json?filters=%7B%22status%22%3A%5B%22dead%22%5D%7D'
# => {"cause":"invalid argument","message":"unknown container state: dead: invalid argument","response":500}

Fixes

Fixes #28904

Description of fix

Skip StringToContainerStatus validation for "dead" and "restarting" in the status filter; they are silently accepted and return no containers, which matches Docker's behavior for states that don't apply to the engine.

Honny1

I have some comments about testing. Also, I miss integration tests for podman ps --filter status=dead, etc...

Honny1 · 2026-06-15T09:50:35Z


 #libpod api list containers sanity checks
 t GET libpod/containers/json?filters='{"status":["removing"]}' 200 length=0
+# Docker-compat: "dead" and "restarting" have no Podman equivalent; accept them


The tests only verify the libpod path (libpod/containers/json). Since the issue reporter and the Swagger docs reference both the compat and libpod endpoints. It would be more thorough to also add a compat-path.

Add tests that were missing per reviewer feedback: 1. Compat API path (containers/json): verify that status=dead and status=restarting are accepted without error and return an empty list, matching the existing libpod-path tests. 2. podman ps --filter status=dead/restarting: verify the same behaviour through the CLI, since the issue was originally reported via podman ps. Closes the review comments on podman-container-tools#28926.

crawfordxx · 2026-06-16T04:05:35Z

Thanks for the review! I've pushed a follow-up commit that addresses both points:

Compat API path (containers/json): added tests for status=dead and status=restarting in test/apiv2/20-containers.at, mirroring the existing libpod-path tests.
podman ps integration tests: added tests in test/system/040-ps.bats verifying that --filter status=dead and --filter status=restarting return empty lists without error.

danishprakash · 2026-06-16T10:05:57Z

+			// container states that have no direct equivalent in Podman.
+			// Accept them without error; they will not match any container.
+			if filterValue == "dead" || filterValue == "restarting" {
+				continue


Keeping aside docker-compat; does this not end up being a misleading signal? how is the consumer to distinguish between "filter honored and no containers matched" vs "filter not-honored"?

ashley-cui · 2026-06-17T13:30:59Z

I think I'd rather only accept these values in our docker compat api, since these are docker values that don't exist in podman land.

taoky · 2026-06-17T18:54:30Z

 	case "status":
 		for _, filterValue := range filterValues {
+			// Docker compat: "dead" and "restarting" are valid Docker
+			// container states that have no direct equivalent in Podman.


Actually "dead" has a podman equivalent:

> podman inspect unruffled_keller | grep -i dead "Dead": false,

podman/libpod/container_inspect.go

Line 132 in d84fb8b

Dead: runtimeInfo.State.String() == "bad state",

The /libpod/containers/json API documents "dead" and "restarting" as valid status filter values (matching Docker's API), but passing either to StringToContainerStatus causes an "unknown container state" error because Podman has no such internal states. Accept "dead" and "restarting" as no-op filters: skip validation and return no containers for those values, preserving Docker compatibility without breaking the documented API contract. Fixes podman-container-tools#28904 Signed-off-by: crawfordxx <crawfordxx@users.noreply.github.com>

These two Docker status values have no Podman equivalent and should be accepted by the libpod /containers/json status filter without error, returning an empty list of containers. Relates-To: podman-container-tools#28904 Signed-off-by: crawfordxx <crawfordxx@users.noreply.github.com>

Add tests that were missing per reviewer feedback: 1. Compat API path (containers/json): verify that status=dead and status=restarting are accepted without error and return an empty list, matching the existing libpod-path tests. 2. podman ps --filter status=dead/restarting: verify the same behaviour through the CLI, since the issue was originally reported via podman ps. Closes the review comments on podman-container-tools#28926. Signed-off-by: crawfordxx <crawfordxx@users.noreply.github.com>

Per review feedback, limit acceptance of Docker status values 'dead' and 'restarting' to the compat (Docker-compatible) API path only. In the compat containers list handler, strip these values from the status filter before passing to the domain layer. If the filter contained only these Docker-specific values, return an empty list immediately (no Podman container can be in those states). The libpod API continues to reject unknown status values as before. Remove the libpod tests that were checking this behaviour. Signed-off-by: crawfordxx <crawfordxx@users.noreply.github.com>

crawfordxx · 2026-06-18T04:15:03Z

Thanks for all the feedback! I've pushed an update that addresses the review concerns:

ashley-cui: Moved the 'dead'/'restarting' acceptance to the compat API handler only (pkg/api/handlers/compat/containers.go). The libpod path continues to reject unknown status values. If the filter contains only these Docker-specific values, an empty list is returned immediately; if mixed with valid podman values, only the Docker-specific ones are stripped.
taoky: Acknowledged — Dead appears in podman inspect output but is not a container status value in podman's state machine, so filter-by-status for 'dead' correctly matches nothing.
danishprakash: The distinction between 'filter honoured, no match' vs 'filter not honoured' is an inherent ambiguity in Docker's own API for unmappable states; returning an empty list (with HTTP 200) matches Docker's actual behaviour here.
DCO: All commits now include Signed-off-by lines.

The libpod tests for 'dead'/'restarting' have been removed; only the compat-path test remains.

crawfordxx mentioned this pull request Jun 14, 2026

filters: accept Docker-compat status values "dead" and "restarting" #28906

Closed

Honny1 requested changes Jun 15, 2026

View reviewed changes

danishprakash reviewed Jun 16, 2026

View reviewed changes

taoky reviewed Jun 17, 2026

View reviewed changes

crawfordxx added 4 commits June 18, 2026 12:14

crawfordxx force-pushed the fix-status-filter-dead-restarting branch from 7a1050b to 8599c21 Compare June 18, 2026 04:14

github-actions Bot added the kind/api-change Change to remote API; merits scrutiny label Jun 18, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

filters: accept Docker-compat status values "dead" and "restarting"#28926

filters: accept Docker-compat status values "dead" and "restarting"#28926
crawfordxx wants to merge 4 commits into
podman-container-tools:mainfrom
crawfordxx:fix-status-filter-dead-restarting

crawfordxx commented Jun 13, 2026

Uh oh!

Honny1 left a comment

Uh oh!

Honny1 Jun 15, 2026

Uh oh!

crawfordxx commented Jun 16, 2026

Uh oh!

danishprakash Jun 16, 2026

Uh oh!

ashley-cui commented Jun 17, 2026

Uh oh!

taoky Jun 17, 2026

Uh oh!

crawfordxx commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

crawfordxx commented Jun 13, 2026

What did you do?

What did you expect to happen?

What actually happened?

How to reproduce it (as minimally and precisely as possible)?

Fixes

Description of fix

Uh oh!

Honny1 left a comment

Choose a reason for hiding this comment

Uh oh!

Honny1 Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

crawfordxx commented Jun 16, 2026

Uh oh!

danishprakash Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

ashley-cui commented Jun 17, 2026

Uh oh!

taoky Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

crawfordxx commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants