Docker Compose传递命令行参数拉取镜像失败问题排查

Got it, let’s figure out why your APP_VERSION=stage/1.1 docker-compose -f docker-compose.yml -f docker-deploy.yml pull application command is failing. I’ve run into similar issues before, so here’s a step-by-step guide to narrow it down:

1. Make Sure Your Compose Files Actually Use the APP_VERSION Variable #

First things first—if your docker-compose.yml or docker-deploy.yml don’t reference ${APP_VERSION} in the application service’s image field, passing the variable won’t do anything.

Check that your service definition looks something like this:

services:
  application:
    image: your-registry/your-app-image:${APP_VERSION}

To verify the variable is being substituted correctly, run this command to see the fully rendered Compose config:

APP_VERSION=stage/1.1 docker-compose -f docker-compose.yml -f docker-deploy.yml config

Look for the image line under the application service. If it doesn’t show stage/1.1 in the tag, either the variable isn’t referenced, or it’s being overridden by another config file.

2. Check Multi-File Override Priority #

When you specify multiple -f flags, later files override settings from earlier ones. If your docker-deploy.yml has a hardcoded image value for the application service (like image: your-registry/your-app-image:prod/2.0), it’ll completely ignore the APP_VERSION variable you passed.

Double-check the docker-deploy.yml to ensure it either uses ${APP_VERSION} for the image tag, or doesn’t override the image field at all.

3. Test Pulling the Image Directly with Docker #

Rule out Compose-specific issues by pulling the image directly using Docker:

docker pull your-registry/your-app-image:stage/1.1

If this fails, the problem is with the image itself, not Compose:

• The stage/1.1 tag might not exist in your registry
• You might not be logged into a private registry (run docker login your-registry first)
• There could be network issues preventing access to the registry
• You might have a typo in the image name or tag (e.g., stage-1.1 instead of stage/1.1)

4. Validate Your Docker Compose Version #

Older versions of Docker Compose (especially v1.x) have bugs with environment variable handling and multi-file configurations. Run this to check your version:

docker-compose --version

If you’re on v1.x, upgrade to a stable v2.x release (you can do this via Docker Desktop, or with pip install --upgrade docker-compose if you installed it via pip).

5. Check Shell-Specific Environment Variable Syntax #

The way you set environment variables depends on your shell—if you’re on Windows, this is a common pitfall:

• Bash/Zsh: APP_VERSION=stage/1.1 docker-compose ... works fine
• PowerShell: Use $env:APP_VERSION="stage/1.1"; docker-compose ... instead
• Windows Command Prompt: Use set APP_VERSION=stage/1.1 && docker-compose ...

If you’re using a Windows shell, incorrect syntax could mean the variable never makes it to Compose.

6. Confirm the Service Name is Correct #

Double-check that the service name in your command (application) matches exactly what’s in your Compose files. A typo like app instead of application will cause the pull to fail.

List all services defined in your combined config to verify:

docker-compose -f docker-compose.yml -f docker-deploy.yml ps --services

If you’ve gone through all these steps and still have issues, share the exact error message you’re getting and snippets of your Compose files— that’ll help pinpoint the problem faster.

内容的提问来源于stack exchange，提问作者EvgeniySharapov