A Dockerfile step fails because add-apt-repository is missing
apt-add-repository: command not foundShort answer
Slim Debian and Ubuntu base images do not ship add-apt-repository. It comes from the software-properties-common package, so install that first, in the same RUN step as apt-get update. A ppa: line only works for Ubuntu releases, so on Debian add the repository file by hand instead.
Fix it fast
1Find out which cause you have
Ask the base image which package owns the command. If the file is missing, the image simply does not have it yet.
docker run --rm ubuntu:24.04 sh -c 'command -v add-apt-repository || echo "not installed"'2Match what you see, then jump to its fix
- 1
The build stops on the RUN line that calls add-apt-repository, and the image has no such file.software-properties-common was never installedFix - 2
software-properties-common itself cannot be installed, or an old cached layer is reused after you changed the Dockerfile.The package lists are stale or empty when the install runsFix - 3
add-apt-repository exists, but the PPA is not found or has no packages for your Debian release.You are adding a ppa: line on DebianFix
- 1
What does the error look like?
apt-add-repository: command not foundadd-apt-repository: command not found
Cause 1 of 3
software-properties-common was never installed
1Check
The man page of add-apt-repository says the command is provided by the software-properties-common package. Container base images are trimmed, so it is not there by default.
docker run --rm ubuntu:24.04 sh -c 'dpkg -s software-properties-common 2>&1 | head -n 2'2Fix
Install the package before the line that adds the repository. Keep update and install in one RUN so the package lists are fresh.
RUN apt-get update \
&& apt-get install -y --no-install-recommends software-properties-common \
&& add-apt-repository -y ppa:user/repository \
&& apt-get update \
&& rm -rf /var/lib/apt/lists/*3Verify
Rebuild without the cache and confirm the step passes.
docker build --no-cache -t apt-check .Confirmed by manpages.ubuntu.com
Cause 2 of 3
The package lists are stale or empty when the install runs
1Check
Look for a RUN apt-get update on its own line. Docker caches that layer, so a later install step can run against an out-of-date list.
grep -n "apt-get" Dockerfile2Fix
Chain apt-get update and apt-get install in the same RUN instruction, as Docker's own build guidance says, and clean the lists at the end of that step.
RUN apt-get update && apt-get install -y --no-install-recommends \
software-properties-common \
&& rm -rf /var/lib/apt/lists/*3Verify
Rebuild with --no-cache once, then normally.
docker build --no-cache -t apt-check .
docker build -t apt-check .Confirmed by docs.docker.com
Cause 3 of 3
You are adding a ppa: line on Debian
1Check
A PPA is an Ubuntu Launchpad Personal Package Archive. It is built for Ubuntu releases, so check which base image your FROM line uses.
grep -n "^FROM" Dockerfile2Fix
On Debian, use the publisher's own Debian repository instructions, or switch the base image to an Ubuntu release the PPA supports. The man page also lets you pass a full sources line instead of ppa:.
FROM ubuntu:24.043Verify
Build and list the sources the image ended up with.
docker run --rm apt-check sh -c 'ls /etc/apt/sources.list.d/'Confirmed by manpages.debian.org
How do I stop it coming back?
- Write apt-get update and apt-get install in one RUN instruction every time.
- Check whether the vendor offers a plain repository file or a signed .deb before reaching for a PPA.
- Pin the base image to a release tag (ubuntu:24.04), so a PPA's supported release does not change under you.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
A dev container port does not open in the browser when Docker runs on a remote host
If your application only accepts calls from localhost, it will reject connections from published ports
Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild.
3 causes, each with a fix