---
title: error / gradle-wrapper-readonly-cache-2026-05-28
source_type: error-note
status: raw
related_branches: [feature-architecture-enforcement-rules]
related_projects: [ca-skeleton]
tags: [error, ca-tmpl, ca-skeleton, runtime, gradle]
created: 2026-05-28
status_label: resolved
---

# error: gradle-wrapper-readonly-cache-2026-05-28

> Layer: `raw/errors/` — 작업 중 마주친 단일 실패·트러블슈팅 기록. 원본은 raw에 영구 보관한다.

## Parent / 부모

- [[raw/branch-notes/feature-architecture-enforcement-rules]] — architecture enforcement 검증 중 Gradle wrapper 실행이 sandbox file-system 제한에 막혔다.
- [[raw/project-notes/ca-skeleton-operational-contract]] — ca-tmpl skeleton 검증 작업의 로컬 실행 환경 이슈다.

## 증상 / Symptom

- 에러 메시지 (원문 그대로):
  ```text
  Exception in thread "main" java.io.FileNotFoundException: /home/donghyeon/.gradle/wrapper/dists/gradle-9.0.0-bin/d6wjpkvcgsg3oed0qlfss3wgl/gradle-9.0.0-bin.zip.lck (Read-only file system)
  ```
- 발생 컨텍스트: `cd src && ./gradlew :app-bootstrap:test --tests '*CleanArchitectureTest'` 실행.
- 발생 시점: 2026-05-28
- 발생 환경: local Codex sandbox, default filesystem permission.
- 재현 가능 여부: `always` — Gradle wrapper가 `~/.gradle` lock/cache 파일을 써야 하는 sandbox 기본 실행에서 재현.

## 재현 절차 / Reproduction

1. ca-tmpl repository root에서 sandbox 기본 권한으로 `cd src && ./gradlew :app-bootstrap:test --tests '*CleanArchitectureTest'` 실행.
2. Gradle wrapper가 `~/.gradle/wrapper/dists/.../*.lck` 파일 생성을 시도한다.
3. 기대 결과: ArchUnit focused test 실행.
4. 실제 결과: `Read-only file system` 때문에 wrapper lock 파일 생성 실패.

## 조사 단계 / Investigation log

- 2026-05-28 — focused architecture test를 sandbox 기본 권한으로 실행 → `~/.gradle` lock 파일 생성 실패.
- 2026-05-28 — 같은 명령을 사용자 승인된 escalated 실행으로 재수행 → Gradle wrapper/cache 쓰기가 가능해지고 테스트 실행 성공.
- 2026-05-28 — 이후 `verifyCleanArchitectureDependencies`, full `./gradlew test`도 escalated 실행으로 검증.

## 근본 원인 / Root cause

- 직접 원인: Gradle wrapper가 사용자 홈의 `~/.gradle/wrapper/dists` 아래 lock 파일을 생성하려 했지만 sandbox 기본 권한에서는 해당 경로가 read-only였다.
- 근본 원인: ca-tmpl workspace 밖의 사용자 홈 cache 디렉터리를 쓰는 Gradle wrapper 동작과 Codex sandbox 기본 write scope가 충돌했다.
- 트리거 조건: Gradle wrapper/cache가 아직 lock 파일을 써야 하는 상태에서 sandbox 기본 권한으로 `./gradlew`를 실행.

## Sources / 근거

- [[raw/branch-notes/feature-architecture-enforcement-rules]] — 이 에러가 발생한 branch 작업과 검증 결과를 기록한다.
- [[raw/daily-notes/2026-05-28]] — 당일 작업 로그에 sandbox Gradle lock 문제와 재실행 사실을 기록한다.

## 해결 / Resolution

- 적용한 조치: 검증 명령을 사용자 승인된 escalated 실행으로 재수행했다.
- 검증 방법:
  - `cd src && ./gradlew :app-bootstrap:test verifyCleanArchitectureDependencies` 성공.
  - `cd src && ./gradlew test` 성공.
- 잔여 위험 / 후속 작업: CI나 일반 로컬 shell에서는 문제가 아닐 가능성이 높지만, sandbox agent 환경에서는 Gradle cache write 권한이 필요하다.

## 회고 / Lessons

- 빨리 감지하는 신호: Gradle wrapper 실행 직후 `~/.gradle/.../*.lck (Read-only file system)` 이 나오면 코드/테스트 문제가 아니라 sandbox filesystem 권한 문제다.
- 예방 체크리스트 항목 후보: Gradle 기반 검증 명령이 `~/.gradle`에 써야 하면 sandbox escalation이 필요할 수 있음을 작업 로그에 남긴다.
- wiki로 끌어올릴 가치가 있는 일반화된 교훈: agent sandbox에서 build tool cache 경로가 workspace 밖이면 검증 실패와 코드 실패를 구분해야 한다.

## Related / 관련

- 트리거된 daily note: [[raw/daily-notes/2026-05-28]]
- 관련 branch note: [[raw/branch-notes/feature-architecture-enforcement-rules]]