Error response from daemon: invalid restart policy: unknown policy 'sometimes'; use one of ... means the restart: value of a service is not one Docker knows. The message lists the four that work: no, always, on-failure and unless-stopped. Pick one of them.

This one gets past docker compose config. The file is accepted, and the error appears only at docker compose up, when Docker tries to create the container.

The error

PS> docker compose -f compose.yaml up -d
...
 Container fix10-cy-q7-web-1 Creating
 service:web:1 Error response from daemon: invalid restart policy: unknown policy 'sometimes'; use one of 'no', 'always', 'on-failure', or 'unless-stopped'
Error response from daemon: invalid restart policy: unknown policy 'sometimes'; use one of 'no', 'always', 'on-failure', or 'unless-stopped'

The file:

name: fix10-cy-q7
services:
  web:
    image: alpine
    command: ["sleep", "1"]
    restart: sometimes

Why it happens

config printed the model with restart: sometimes in it and exit code 0, so on this Compose version the value is not checked while the file loads. It is passed on to the Docker engine when the container is created, and the engine refuses it with the message above. up exited with code 1 after the network was created and before any container existed.

That order matters for checks in a pipeline: a docker compose config step alone did not catch this mistake in the test. Only creating the container did. The message is printed twice, once on the service's progress line (service:web:1) and once as the final error, and both carry the full list of accepted policies. After the failed run, docker compose down removed only the network, since no container had been created.

The fix

name: fix10-cy-q7
services:
  web:
    image: alpine
    command: ["sleep", "1"]
    restart: on-failure
PS> docker compose -f compose.fixed.yaml up -d
...
 Container fix10-cy-q7-web-1 Started
PS> docker inspect fix10-cy-q7-web-1 --format '{{.HostConfig.RestartPolicy.Name}}'
on-failure

With on-failure, the container was created and started, and docker inspect shows the policy the engine stored. Only on-failure was run in this test; the other three names come from the engine's own message, so copy the spelling from there, hyphens included.

How it was reproduced

Docker Desktop on Windows 11, Docker Compose v5.7.0, engine 29.9.3, Windows PowerShell 5.1, the cached alpine image. A one-service compose.yaml with restart: sometimes passed docker compose -f compose.yaml config and failed up -d with the message above and exit code 1; with on-failure the container started and docker inspect printed the policy. Both runs were removed with docker compose down. The project name fix10-cy-q7 is the test's own.

Frequently asked

What does invalid restart policy unknown policy mean in docker compose?
The restart value of a service is not one the Docker engine accepts. The message lists them: no, always, on-failure and unless-stopped.
Why does docker compose config not catch an invalid restart policy?
In the test with Compose v5.7.0, config accepted restart: sometimes with exit code 0. The engine refused it only when up created the container.
Which restart policies does docker compose support?
The engine's message names four: no, always, on-failure and unless-stopped. In the test on-failure was accepted and docker inspect showed it.

More decoded errors in the Fixes category. A value that Compose itself refuses while loading the file, such as an invalid memory size, is covered in mem_limit invalid size.