Docker Compose Config Not Applying: 4 Real Errors and the Fixes

Dockerself-hostedDevOpsDocker Composesystemd

The sentence that makes self-hosted operations miserable is: "I changed the config. Why didn't it take effect?"

That sentence shows up constantly, and it is almost never an application bug. More often it is a mismatch between how the deployment tool decides what "applied" means and what you intuitively expect it to mean. I manage a dozen or so Compose projects on one machine, and nearly every one of my repeat mistakes collapses into a single fact: **a container's configuration is fixed at the moment the container is created.** restart just runs the process again inside that same container. It will never re-read your YAML.

This article is not about standing up a service. It is about one thing: why the configuration did not apply, and how to identify which layer ate it within five minutes. Every command here is copy-pasteable.

Disclosure: this post contains Amazon affiliate links. Prices are unchanged if you buy through them, and I earn a small commission. The hardware mentioned is self-purchased, and prices reflect typical ranges as of publication — check the product page for current pricing.

The mental model: restart and up -d are not the same operation

The first mistake almost everyone makes is treating docker compose restart as "apply the new config." It is not.

Environment variables, port mappings, mount paths, the command, the run user, the image ID — all of these are written into the container's own record when the container is created. restart sends a stop signal to the main process and starts it again **inside the same container**. Since the container was never replaced, none of those fields can have changed.

So after restart, all of the following are guaranteed to be unchanged:

Edits to `ports:`, `volumes:`, `environment:`, or `command:` in `docker-compose.yml`
Changed values in `.env` (Compose reads `.env` while **rendering the service definition**, not while starting a process)
Edits to the file referenced by `env_file:` (resolved into the definition at the same stage)
A new image (the container still runs the image it was created from)

The command that actually applies changes is docker compose up -d. Here is how it works: Compose reads the Compose file, resolves every variable, computes a hash of the resulting service definition, and stores that hash as a label on the container when it creates it. On the next up -d, it computes the hash again and compares it to the label on the running container. **Different hash, new container. Same hash, Compose leaves it alone.**

That single mechanism also explains the other common confusion: "I changed the config, and up -d did nothing." Nothing is broken — nothing actually differed. Either the key you edited never made it into the rendered result (a typo'd key, for example), or something else is overriding it.

One more version trap: the old hyphenated docker-compose (the Python-based V1) is no longer in current packages. As of July 2026, getting docker-compose: command not found on a fresh Ubuntu box is **expected behavior**, not a broken machine. The current form is docker compose with a space — a Go plugin installed alongside Docker Engine, commonly referred to as Compose V2. Use docker compose version to confirm.

The command ladder: match the rung to what you edited

Start from the cheapest rung and climb only as far as your edit requires. This saves both needless rebuilds and avoidable downtime.

What you changed	Command to run	Recreates the container?
Process crashed, just bring it back	`docker compose restart web`	Never — it never recreates
Service reads config from a host bind mount	`docker compose exec web nginx -s reload`	No, and it drops no connections
Edited the Compose file, `.env`, or `env_file`	`docker compose up -d`	Only if the definition hash changed
Edited the Dockerfile or application code	`docker compose up -d --build web`	Builds first, then recreates
Suspect a stale build cache	`docker compose build --no-cache web`, then `up -d web`	Rebuilds every layer
Changed an image tag and need the new one	`docker compose pull web`, then `up -d web`	Recreates only after the pull
Want to force-refresh the runtime environment	`docker compose up -d --force-recreate`	Unconditionally recreates

The two most counter-intuitive rows are the first two. restart is not a reload, and exec ... reload is the reload. If your nginx config directory is bind-mounted from the host, editing the file on the host does not require replacing the container at all — reload in place instead, which is far gentler and does not drop the connections the container is currently serving.

Conversely, "update the image" requires **two commands**. pull downloads the new image; up -d is what notices the image ID changed and recreates the container. Run up -d without pulling and you will quietly keep running last month's latest, with no error at all.

One automation-related detail is worth remembering: up -d returns as soon as the containers are created, which is why a deploy script that runs up -d and immediately probes with curl **often fails on the first try**. Use up -d --wait to block until every service that declares a healthcheck reports healthy, exiting non-zero if one never gets there. That flag is only as good as the check behind it, so write the healthcheck properly before leaning on it in automation.

Error 1: you changed .env and the service still uses the old values

This is the single most frequent one I see. There is no exception in the logs. The service simply quietly ignores your edit.

The observable symptom usually shows up application-side: it cannot reach the database, it is listening on the old port, or the config value printed in its logs differs from what you just wrote.

The cause is that .env is read while Compose **renders the service definition**, and the resolved result is baked into that definition. restart never re-renders.

Diagnostic order:

# 1. Look at the final rendered definition — did my value make it in?
docker compose config

# 2. Read the hash label stored on the container
docker inspect --format '{{ index .Config.Labels "com.docker.compose.config-hash" }}' 

# 3. Read the environment variable the container actually has
docker compose exec web env | grep MY_VAR

If step 1 prints your new value and step 3 still shows the old one, you simply did not recreate. Run docker compose up -d . If step 1 still shows the old value, the problem is at the rendering layer — commonly because the file referenced by env_file: does not exist, or because you are in the wrong directory. Compose takes the project name and resolves the file relative to the current directory, so running it one level up yields no configuration file provided: not found.

Error 2: the systemd drop-in is written but the service behaves identically

The scenario: you do not want to edit /lib/systemd/system/nginx.service directly (a package upgrade will overwrite it), so you write a drop-in. After systemctl restart, nothing changed.

The most common error text looks like this:

Failed to read drop-in file /etc/systemd/system/nginx.service.d/override.conf:
Syntax error

Or a quieter variant, where nothing is reported at all but your file is simply never read:

# Named override.txt — systemd ignores it outright, because it requires .conf

systemd's rules for drop-ins are strict:

The directory must be named `.d`, i.e. `nginx.service.d`, not `nginx.d`
The filename **must end in `.conf`**
It must live under `/etc/systemd/system/`, which takes precedence over `/run/` and `/usr/lib/`
Multiple drop-ins are applied in lexicographic order of filename

After writing one you **must** run systemctl daemon-reload. systemd reads unit files into memory and does not look at disk again, so editing the file without reloading is equivalent to having done nothing:

sudo systemctl edit nginx.service      # interactive drop-in editor, hardest to get wrong
sudo systemctl daemon-reload
sudo systemctl restart nginx

To confirm what systemd actually used, run systemctl cat nginx.service — it shows the **merged, effective** unit content, which is far more reliable than reading files on disk yourself.

Error 3: "Service has more than one ExecStart= setting"

This one appears when a drop-in tries to override ExecStart:

nginx.service: Service has more than one ExecStart= setting in drop-in.
Refusing.

ExecStart= is a list-type directive. Writing another one in a drop-in **appends** rather than overrides, so you end up with two. The rule is: **clear it with an empty assignment first, then set the new value.**

[Service]
ExecStart=
ExecStart=/usr/local/bin/nginx -c /etc/nginx/my.conf

The same applies to other list directives — adding OnCalendar= in a timer and getting two firings, for example, or stacking Environment=. Single-value directives are simply overwritten when you write them; no clearing needed.

The opposite trap: **dependencies can be added but never removed.** Requires=, After= and friends cannot be unset through a drop-in. To genuinely replace a unit, use systemctl edit --full to write a complete unit, or mask and redefine it.

To audit a whole machine for units that have been overridden by drop-ins — or, worse, frozen by a full copy — run:

systemctl daemon-reload
systemd-delta --type=overridden

A full copy of the unit file is the worst case: it freezes upstream's version, so package upgrades will never reach you.

Error 4: the unit is correct but the service will not start

Drop-in syntax is valid, the daemon-reload ran, and systemctl start still fails. The errors typically look like:

myapp.service: Failed at step EXEC spawning /opt/myapp/bin/myapp: No such file or directory

Or the more common restart loop:

myapp.service: Start request repeated too quickly.
myapp.service: Failed with result 'exit-code'.
systemd: Failed to start MyApp daemon.

The first means the ExecStart path does not exist or is not executable — check with ls -l. The second means the app started and exited immediately, and Restart=on-failure brought it straight back, hitting the rate limit. In that case **stop reading the restart policy and find out why the app exited**:

sudo systemctl status myapp.service
sudo journalctl -u myapp.service -n 50 -o cat   # strip systemd's wrapper, read the app's own first error

The -o cat step matters. systemd only tells you "the process exited"; the actual cause lives in the service's own stdout/stderr, and you cannot see it without stripping the wrapper.

Validate syntax before changing anything and you will avoid a lot of blind restarts:

sudo systemd-analyze verify /etc/systemd/system/myapp.service

It parses the unit, reports syntax errors and unknown directives, and checks whether the executable named in ExecStart= exists.

The version-specific trap: containers get recreated after a Compose upgrade

Reconciliation in Compose changed considerably during 2026, and if you upgraded recently these are worth knowing:

**v5.2.0 (2026-06-23)** introduced a new reconciliation algorithm between observed and expected container state, flagged as a breaking change in a minor release.
**v5.4.0 (2026-08-03)** modeled volume recreation and network lifecycle in the reconcile plan, so volume and subnet changes became visible before they were applied. It also fixed multi-platform builds to use the platform image-manifest digest.
**v5.5.0 (2026-08-17)** overhauled image digest reconciliation. **Note: the first time you run `compose up` after upgrading, existing containers may be recreated**, because the digest comparison moved to a new model. This is a one-time event; once the digests settle, unnecessary recreation stops.

The practical consequence: if your script diffs container IDs to decide whether "anything changed," verify the first run after the upgrade separately instead of treating it as an anomaly.

A five-minute triage checklist

Configuration did not apply. Walk these in order:

# 1. Render layer: is my change in the final definition?
docker compose config | grep -i MY_VAR

# 2. Definition layer: did the hash change?
docker inspect --format '{{ index .Config.Labels "com.docker.compose.config-hash" }}' 

# 3. Container layer: did the environment variable actually arrive?
docker compose exec  env | grep MY_VAR

# 4. Mount layer: bind mount or named volume?
docker inspect  --format '{{json .Mounts}}'

# 5. Image layer: which image ID am I really running?
docker inspect  --format '{{.Image}}'
docker image inspect : --format '{{.Id}}'

Step 4 gets skipped most often. Editing a file on the host and not seeing it inside the container is another flavor of "my change did not apply" — if that mount is a named volume rather than a bind mount, the host directory and the container directory are two completely independent copies of the data.

Closing: make the mechanism a habit

I kept exactly three rules from all of this:

1. **After editing a Compose file, always run docker compose config first** and read the rendered result. Never edit and immediately up. This one habit prevents the large majority of low-level mistakes.

2. **restart is only for reviving a crashed process.** Any configuration change goes through up -d. Add --build when build artifacts changed, and pull first when the image changed.

3. **Never edit files directly under /lib/systemd/system/ or /usr/lib/systemd/system/.** Use drop-ins, run daemon-reload, then verify with systemctl cat.

One more note: the pile of small services on my machine is fundamentally "one small host plus a lot of containers." If you are building a similar home lab, these three items are what I actually use — a Raspberry Pi 5 as an always-on node, a Cat6 cable for the rack run, and a microSD card holding configs and logs. All self-purchased, prices confirmed on the product page.

👉 View Raspberry Pi 5 (8GB) on Amazon

👉 View Amazon Basics Cat6 Ethernet Cable on Amazon

👉 View Amazon Basics microSD Card 128GB on Amazon