Subscribe

Why your Docker image should use CMD and not ENTRYPOINT when ECS overrides the command

An ECS run-task override can replace a container's command but not its entrypoint. With ENTRYPOINT in the image, the override becomes arguments to your app and the one-off task starts the API server instead. Here is how to see it and catch it in CI.

Why your Docker image should use CMD and not ENTRYPOINT when ECS overrides the command

This is a small gotcha, but it cost me a deploy. When you run a one-off ECS task with a command override, ECS replaces the container's command. It can't touch the ENTRYPOINT. If your image starts the app with an exec form ENTRYPOINT, your override is passed to the app as arguments, and the app happily starts serving HTTP instead of doing the job you asked for.

I hit this while moving our goose migrations out of the container start command and into a separate ECS task. The full setup is in running goose migrations as a one-off ECS task before updating the service. Here we will only look at the ENTRYPOINT part, because it applies to any one-off task: migrations, backfills, a cleanup script.

How it went wrong

Before the change, the Dockerfile ended like this:

ENTRYPOINT ["/bin/sh", "-c", "goose -dir ./migrations postgres \"$DATABASE_URL\" up && ./app"]

When I took goose out, I changed that line to the obvious thing:

ENTRYPOINT ["./app"]

Then the pipeline started the migration task with an override like ["/bin/sh", "-c", "goose ... up"]. The task started fine, it just never migrated anything, and it never stopped either, because it was busy being an API server. The CI step sat there waiting for a task that had no reason to exit. The fix went in the next morning: one word in the Dockerfile and a check in the pipeline.

Seeing it with docker run

docker run IMAGE args... follows the same rule as the ECS override, so you can reproduce this on your laptop. I built two images from same base, one with ENTRYPOINT ["./app"] and one with CMD ["./app"], and gave both the migration command. The base is a normal multi-stage golang image like the one in creating a multi-stage Dockerfile for a golang web service, with goose copied in.

The CMD image did what I wanted:

docker run --rm -e DATABASE_URL="$URL" notes-cmd:dev \
  /bin/sh -c 'goose -dir ./migrations postgres "$DATABASE_URL" up'
OK   20261119090000_create_notes.sql (6.03ms)
OK   20261119093000_add_notes_author.sql (5.38ms)
goose: successfully migrated database to version: 20261119093000

The ENTRYPOINT image started the app:

docker run -d --name ep-test -e DATABASE_URL="$URL" notes-ep:dev \
  /bin/sh -c 'goose -dir ./migrations postgres "$DATABASE_URL" up'
docker logs ep-test
docker inspect ep-test --format 'path={{.Path}} args={{json .Args}}'
app listening on :8080
path=./app args=["/bin/sh","-c","goose -dir ./migrations postgres \"$DATABASE_URL\" up"]

There it is. The whole migration command became os.Args[1:] of a program that never looks at its arguments. No error, no warning, nothing in the logs that says "you asked for goose".

A side note I didn't know before trying this: when a Dockerfile sets ENTRYPOINT, any CMD inherited from the base image is reset to empty. docker image inspect showed cmd=null on the ENTRYPOINT image even though the base had CMD ["./app"].

The rules, in short

Docker and ECS use the same model. The final process is ENTRYPOINT followed by CMD.

  • An override in docker run IMAGE ... or in an ECS containerOverrides[].command replaces CMD.
  • Nothing in an ECS run-task override replaces ENTRYPOINT. The ContainerOverride type has command, environment, environmentFiles, cpu, memory, memoryReservation and resourceRequirements, and that's all.
  • A shell form ENTRYPOINT (ENTRYPOINT ./app without the brackets) is worse. It ignores CMD and every argument, so the override is simply dropped. I tried it with a tiny alpine image and the override never ran.
  • The task definition can also set entryPoint on the container, and that wins over the image. So the image being clean isn't enough on its own.

Locally you can escape with docker run --entrypoint, which is probably why this doesn't hurt until you're on ECS.

So the fix in the Dockerfile is:

# CMD, not ENTRYPOINT: the migration task replaces this with a command override.
CMD ["./app"]

Failing fast in the pipeline

One word in a Dockerfile is easy to undo in six months by someone who likes ENTRYPOINT. Fair enough, lots of people do. So the pipeline checks two places before it starts the migration task.

First the task definition, right after we render it with the new image:

#!/usr/bin/env bash
# Fail if the named container in a task definition JSON sets entryPoint.
set -euo pipefail
file="$1" name="$2"
len=$(jq -r --arg n "$name" \
  '[.containerDefinitions[] | select(.name == $n) | .entryPoint // []] | flatten | length' "$file")
if [ "$len" != "0" ]; then
  echo "::error::container $name sets entryPoint in the task definition. A command override would be appended to it as arguments. Remove entryPoint and let the image's CMD start the app."
  exit 1
fi
echo "ok: $name has no entryPoint"

The .entryPoint // [] handles containers that don't have the field at all, and flatten | length gives 0 when nothing is set. I ran it against two sample task definitions, one clean and one with "entryPoint": ["./app"], and got exit 0 and exit 1.

Second, the image itself, right after docker build:

#!/usr/bin/env bash
# Fail if a built image has an ENTRYPOINT baked in.
set -euo pipefail
ep=$(docker image inspect "$1" --format '{{json .Config.Entrypoint}}')
if [ "$ep" != "null" ]; then
  echo "::error::image $1 has ENTRYPOINT $ep. Use CMD so a command override can replace it."
  exit 1
fi
echo "ok: $1 has no ENTRYPOINT"
ok: notes-cmd:dev has no ENTRYPOINT
::error::image notes-ep:dev has ENTRYPOINT ["./app"]. Use CMD so a command override can replace it.

Our pipeline only had the task definition check at first. The image check is cheap though and catches the case that actually bit me, so I'd run both. Both fail in under a second, which beats waiting on a task that will never stop.

When you really need an ENTRYPOINT

Sometimes you do want one, for example a small script that sets things up before the app starts, or an init like tini. That is fine as long as the wrapper hands over to whatever CMD is:

#!/bin/sh
set -e
echo "wrapper: setting things up"
exec "$@"
COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
CMD ["./app"]

With this, an override replaces ./app and the wrapper runs it. I checked both ways: without an override it printed the wrapper line and started the app, with /bin/sh -c 'echo migrating' it printed the wrapper line and then migrating. If you go this way, let the image check above allow your wrapper's path instead of failing on any ENTRYPOINT.

Versions for the record: Docker 29.8 with alpine 3.23 images and AWS CLI v2.38. The ECS rule has been the same for years though.

That's all there is to it. Keep the start command in CMD, and let the pipeline shout when somebody moves it.