# WARNING: Build cache was invalidated by environment variable 'GIT_COMMIT' change.

- **ID:** `docker/build-cache-invalidation-due-to-env`
- **Domain:** docker
- **Category:** build_error
- **Verification:** ai_generated
- **Fix Rate:** 85%

## Root Cause

Docker build uses --build-arg with a dynamic variable (e.g., git commit hash) that changes each build, causing all subsequent layers to be rebuilt.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Docker 24.0.6 | active | — | — |
| Docker 25.0.2 | active | — | — |

## Workarounds

1. **Place the ARG declaration after all stable layers (e.g., after apt-get install) so only final layers are rebuilt, e.g., 'ARG GIT_COMMIT' at the end of Dockerfile.** (85% success)
   ```
   Place the ARG declaration after all stable layers (e.g., after apt-get install) so only final layers are rebuilt, e.g., 'ARG GIT_COMMIT' at the end of Dockerfile.
   ```
2. **Use a separate label instruction like 'LABEL git.commit=$GIT_COMMIT' after caching dependencies, keeping build-arg only for metadata.** (90% success)
   ```
   Use a separate label instruction like 'LABEL git.commit=$GIT_COMMIT' after caching dependencies, keeping build-arg only for metadata.
   ```

## Dead Ends

- **** — Removing the --build-arg entirely loses the dynamic value needed for labeling or debugging. (60% fail)
- **** — Adding the ARG after RUN commands in Dockerfile still invalidates cache for those layers. (90% fail)