How to Fix Docker Build Requires Exactly 1 Argument
In this blog post, we'll discuss what causes the docker build requires exactly 1 argument” error and how to resolve it.
A common error you might encounter when building a Docker image using the docker build command is the “docker build requires exactly 1 argument” error.
In this blog post, we'll discuss what causes the error and offer solutions to effectively resolve it. Let's get started!
Creating a Sample Dockerfile
Before we explore the error scenarios, let’s start by creating a sample Dockerfile. This will be our foundational setup to demonstrate different instances where the error can occur.
Create a folder named docker-build-error-demo, and inside this folder, create a file named Dockerfile containing the following code snippet:
FROM alpine:3.16
ARG DEFAULT_MESSAGE="Hello World!"
RUN echo "Default message: ${DEFAULT_MESSAGE}"Learn how to build a Docker image with Dockerfile from scratch in our blog post: How to Build a Docker Image With Dockerfile From Scratch.
Four Common Causes of the "docker build requires exactly 1 argument" Error
In this section, we'll explore the four most common reasons behind the 'docker build requires exactly 1 argument' error and provide solutions for each.
#1 Omitting the dot (.) in the docker build command
One of the most common reasons why the “docker build requires exactly 1 argument” error occurs is because you forgot to add a dot(.) in the docker build command.
What is this dot (.) and why do you need it?
To explain, let's look at an example. Make sure you’re inside the docker-build-error-demo folder at the command line, then run the following command:
docker build -t my-app
You’ll encounter the error: "docker buildx build" requires exactly one argument”, as shown below:
Note: In the error message, notice the word buildx. It indicates that Docker is using buildx as the default builder. docker buildx is an extended version of docker build with more capabilities.
So, why did this error occur?
This error occurred because we didn’t specify the build context in the Docker command. The term "build context" refers to a directory containing the application’s source code and the Dockerfile to be used in creating the image. This directory is vital in the Docker build process as it serves as the source of files and instructions for building the Docker image.
In our scenario, the folder docker-build-error-demo is our intended build context, but we didn’t pass it to the docker build command.
So, how are we supposed to specify the build context? The answer is simple: by using a dot (.), assuming we're already inside the directory containing the Dockerfile in our terminal. This dot represents the current directory. In our command, we didn’t add this dot, leading to the error.
Let’s add the dot and run the command again, as shown below:
docker build -t my-app .
Now, the command runs successfully without any error, as shown below:
#2 Incorrect dashes in command flags
Another common trigger for the “docker build requires exactly 1 argument” error is using incorrect dashes in your command.
Make sure you're in the docker-build-error-demo folder, and then run the following command:
docker build –t my-app .
Surprisingly, we have the error: "docker build requires exactly 1 argument”, as shown below:
At first glance, the command appears correct – it includes the dot (.) indicating the build context. So, what went wrong?
The issue lies in the use of an en dash (–) instead of a hyphen (-) in the -t flag. Such mistakes are particularly common when you copy and paste commands from some sources, where dashes can be converted to different characters.
En dashes are slightly longer than hyphens and are used differently. However, in command lines, such distinctions are critical: only hyphens are recognized for flag specifications.
To avoid such errors, it's best to type out Docker commands manually. Here’s how the command should look with the correct dash:
docker build -t my-app .
After running the command, you’ll see a successful build, as shown below:
#3 Missing quotes around the pathname with spaces
We learnt that when building a Docker image, you use a dot (.) in the docker build command to specify the build context (assuming, in the terminal, you’re inside the folder that contains the Dockerfile). But what if the Dockerfile is not in the current folder but, let’s say, inside another folder within the current directory? In such cases, you need to provide the path to the Dockerfile in the docker build command.
Let's see this in practice. Create a folder named docker file inside the docker-build-error-demo folder. (Note that there's a space in the folder name.) Move the Dockerfile inside the docker file directory, then run the following command:
docker build -t my-app ./docker file
After executing this command, you'll encounter the "docker build requires exactly 1 argument" error, as shown below:
The error here arises due to the space in the folder name docker file. In command-line syntax, spaces are interpreted as separators for different arguments. Hence, the command mistakenly reads ./docker and file as two separate inputs.
The solution is straightforward – we need to enclose the pathname in quotes.
Now that we understand the reason for the error let's run the corrected command:
docker build -t my-app "./docker file"
Executing this command, we find that the build process runs without any error, as shown below:
#4 Missing quotes in build arg variable values with spaces
Another reason you might encounter the “docker build requires exactly 1 argument” error is due to spaces in the values of build arg variables.
Inside our Dockerfile, we've defined a build argument named DEFAULT_MESSAGE. Let's try to override this build arg variable while running the docker build command.
Run the following command:
docker build --build-arg DEFAULT_MESSAGE=Hello from Docker -t my-app "./docker file"
After running this command, you'll see the following error message:
This error is triggered because the overridden value of DEFAULT_MESSAGE, which is Hello from Docker, includes spaces. The command line interprets this as three separate arguments due to the lack of quotes.
To fix this, we need to wrap the argument value in quotes. Let's execute the correct command:
docker build --build-arg DEFAULT_MESSAGE="Hello from Docker" -t my-app "./docker file"
Now, the build process runs successfully, as shown below:
Conclusion
In this blog post, we discussed four common reasons behind the "docker build requires exactly 1 argument" error and learned how to solve them effectively.
Interested in learning more about Docker? Check out the following courses from KodeKloud:
