# docker build: Usage, Options & Common CI Errors

> How docker build works: building an image from a Dockerfile, tagging, build args, target stages, and the build failures you hit in CI.

Source: https://latchkey.dev/learn/command-reference/docker-build-command  
Updated: 2026-06-25

Build an image from a Dockerfile - and survive the build doing it in CI.

docker build packages a build context and a Dockerfile into an image. In modern Docker it invokes BuildKit by default. This page covers the flags you use most and the build failures that break CI.

## What it does

docker build sends a build context (a directory, usually the current one) to the daemon and executes each Dockerfile instruction to produce a layered image. The final argument is the context path, not the Dockerfile path.

## Common usage

```Terminal
docker build -t myapp:latest .
docker build -t myapp:1.2.3 -f docker/Dockerfile .
docker build --build-arg NODE_ENV=production -t myapp .
docker build --target builder -t myapp-builder .
docker build --no-cache --pull -t myapp:ci .
```

## Options

| Flag | Does |
| --- | --- |
| -t, --tag | Name and optionally tag (name:tag) |
| -f, --file | Path to the Dockerfile (default ./Dockerfile) |
| --build-arg | Set a build-time ARG value |
| --target | Build a specific stage in a multi-stage build |
| --no-cache | Ignore the layer cache |
| --pull | Always pull a newer base image |
| --platform | Target platform, e.g. linux/amd64 |

## Building without the cache

--no-cache makes this build ignore every cached layer; it does not delete the cache, so the disk is unchanged and the next build without the flag reuses layers again. Reach for it when a build is producing a stale result you cannot explain - an apt or apk index frozen at whatever a RUN step saw days ago is the usual culprit - and pair it with --pull, which also re-resolves the base image tag. In CI it costs you the whole build every time, so it belongs on a scheduled or manual job rather than on every push.

```Terminal
docker build --no-cache --pull -t myapp:ci .   # ignore layers AND re-pull the base
docker builder prune -af                       # actually free the cache from disk
```

## Common errors in CI

A frequent CI failure is "failed to compute cache key: ... not found" - the Dockerfile COPYs a path that is not in the build context (often because of .dockerignore or because CI runs from a different working directory). Fix by running build from the repo root with the correct context, e.g. docker build -f path/to/Dockerfile . , and confirm the file is not excluded by .dockerignore. A second is running out of disk: "no space left on device" mid-build - prune with docker system prune -af or use a larger runner.

## FAQ

### docker build: Usage, Options & Common CI Errors?

docker build packages a build context and a Dockerfile into an image. In modern Docker it invokes BuildKit by default. This page covers the flags you use most and the build failures that break CI.

### What it does?

docker build sends a build context (a directory, usually the current one) to the daemon and executes each Dockerfile instruction to produce a layered image. The final argument is the context path, not the Dockerfile path.

### Building without the cache?

--no-cache makes this build ignore every cached layer; it does not delete the cache, so the disk is unchanged and the next build without the flag reuses layers again. Reach for it when a build is producing a stale result you cannot explain - an apt or apk index frozen at whatever a RUN step saw days ago is the usual culprit - and pair it

### Common errors in CI?

A frequent CI failure is "failed to compute cache key: ... not found" - the Dockerfile COPYs a path that is not in the build context (often because of .dockerignore or because CI runs from a different working directory). Fix by running build from the repo root with the correct context, e.g. docker build -f path/to/Dockerfile .

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt