# failed to register layer: Error processing tar file(exit status 1): write /app/node_modules/.cache/...: no space left on device

- **ID:** `docker/tar-file-too-large-for-layer`
- **Domain:** docker
- **Category:** resource_error
- **Verification:** ai_generated
- **Fix Rate:** 85%

## Root Cause

The Docker build context or intermediate layer contains a large file (e.g., node_modules cache) that exceeds the available disk space in the Docker storage driver (overlay2).

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Docker Desktop 4.23.0 | active | — | — |
| Docker Engine 24.0.7 | active | — | — |
| overlay2 storage driver | active | — | — |
| Node.js 18.18.0 | active | — | — |
| npm 10.2.0 | active | — | — |

## Workarounds

1. **Add a .dockerignore file to exclude large directories like node_modules: '**/node_modules/**' and '**/.cache/**' to reduce the build context size.** (90% success)
   ```
   Add a .dockerignore file to exclude large directories like node_modules: '**/node_modules/**' and '**/.cache/**' to reduce the build context size.
   ```
2. **Increase the disk image size in Docker Desktop: Settings > Resources > Advanced > Disk image size (e.g., from 64GB to 128GB). Then apply and restart Docker.** (80% success)
   ```
   Increase the disk image size in Docker Desktop: Settings > Resources > Advanced > Disk image size (e.g., from 64GB to 128GB). Then apply and restart Docker.
   ```
3. **Use multi-stage builds to copy only necessary artifacts: 'COPY --from=builder /app/dist /app' and avoid copying entire node_modules into the final stage.** (85% success)
   ```
   Use multi-stage builds to copy only necessary artifacts: 'COPY --from=builder /app/dist /app' and avoid copying entire node_modules into the final stage.
   ```

## Dead Ends

- **Adding more RAM to the Docker VM (Docker Desktop settings)** — RAM allocation does not affect disk space in the storage driver; the error is about disk space, not memory. Increasing RAM may help other issues but not this one. (90% fail)
- **Running 'docker system prune -a' to clean all unused data** — While pruning frees space, it does not prevent the build from generating large layers again; the error will recur if the same large file is in the context. (50% fail)
- **Setting 'DOCKER_BUILDKIT=0' to disable BuildKit** — Disabling BuildKit uses the legacy builder which has the same disk space limitation; it may even be more space-intensive due to less efficient caching. (75% fail)