ADD failed: failed to download

The error “ADD failed: failed to download” occurs when the ADD instruction in a Dockerfile tries to fetch a file from a URL but the download fails for any reason.

What It Means

Docker’s ADD instruction supports downloading files from remote URLs during image build. When the URL is unreachable, the server returns an error, or the download times out, Docker raises this error and aborts the build.

Why It Happens

• The URL is incorrect or the file was moved or deleted on the server.
• The remote server requires authentication (e.g., a private S3 bucket).
• The server returns an HTTP error (404, 403, 500).
• The Docker build environment has no internet access or is behind a proxy.
• The URL uses a protocol not supported by ADD (e.g., FTP, SCP).
• The download times out due to slow network or large file size.

How to Fix It

1. Verify the URL with curl

curl -I https://example.com/file.tar.gz

2. Use RUN with curl or wget instead of ADD

RUN curl -fsSL https://example.com/file.tar.gz -o /tmp/file.tar.gz

3. Configure Docker to use a proxy

# Create ~/.docker/config.json
{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy:8080",
      "httpsProxy": "http://proxy:8080"
    }
  }
}

4. Add authentication credentials

RUN curl -u username:password -fsSL https://private.example.com/file.tar.gz -o /tmp/file.tar.gz

5. Copy the file locally instead

COPY ./local-file.tar.gz /tmp/

FAQ