설치 · 실행 · 테스트 중 자주 겪는 문제를 증상 · 원인 · 해결로 적는다.

web(React) 화면이 비어 있다

• 증상: 테스트 · 빌드는 통과하는데 브라우저에서 web 이 빈 화면이고 콘솔에만 오류가 난다.
• 원인: react 와 react-dom 버전이 다르다. ^ 범위로 두면 pnpm 이 둘을 따로 고를 수 있다.
• 해결: pnpm-workspace.yaml 카탈로그에서 두 패키지를 Expo 가 정한 같은 버전으로 고정한다. 올릴 때도 카탈로그에서 함께 바꾼다.

site(Next)가 엉뚱한 서버를 부른다

• 증상: API_URL 을 바꿔 띄웠는데 브라우저의 /api 요청이 예전 서버로 간다.
• 원인: next.config.ts 의 rewrites 주소는 next build 때 정해진다. API_URL 을 실행할 때 읽는 것은 서버 컴포넌트뿐이다.
• 해결: 빌드할 때 준다: API_URL=http://127.0.0.1:8103 pnpm --filter @app/site build. 이미지는 빌드 인자 API_URL.

앱의 요청이 502 나 프록시 오류로 실패한다

• 증상: 화면에 notes 서버에 연결할 수 없습니다 같은 오류가 뜨거나, 개발 서버 로그에 /api 프록시 오류(ECONNREFUSED 127.0.0.1:8003)가 난다.
• 원인: 앱은 gateway 하나로 부른다. 앞의 것은 gateway 는 떴는데 그 뒤의 서버가 없고, 뒤의 것은 gateway 자체가 없다. 앱만 따로 띄우면(pnpm --filter @app/web dev) 둘 다 생긴다.
• 해결: 루트 pnpm dev 로 서버 셋과 gateway 를 같이 띄운다. 따로 띄운 서버에 붙일 때는 gateway 에 NOTES_URL · TAGS_URL · ACTIVITY_URL 을 준다.

pnpm install 이 설치 스크립트 때문에 실패한다

• 증상: ERR_PNPM_IGNORED_BUILDS 와 함께 설치가 멈춘다.
• 원인: pnpm 12 는 의존성의 설치 스크립트를 기본으로 막고, 막힌 것이 있으면 실패한다.
• 해결: development.md 처럼 allowBuilds 에 적는다.

테스트가 ECONNREFUSED 127.0.0.1:5432 로 실패한다

• 원인: 테스트는 docker 의 Postgres 를 쓰는데 떠 있지 않다.
• 해결: pnpm infra. 루트의 pnpm test · pnpm dev 는 먼저 띄우지만 pnpm --filter 로 하나만 돌릴 때는 직접 띄운다.

5432 포트가 이미 쓰이고 있다

• 원인: 이 컴퓨터에 다른 Postgres 가 떠 있다.
• 해결: docker/.env.example 을 docker/.env 로 복사해 POSTGRES_PORT 를 바꾸고, 서버 · 테스트에는 같은 값으로 PGPORT 를 준다.

이름을 바꾼 뒤 DB 가 비어 있다

• 원인: pnpm rename 이 compose 프로젝트 이름을 바꿔서 Postgres 볼륨도 새 이름(<slug>_db)으로 만들어진다.
• 해결: 템플릿 상태로 띄운 적이 있다면 예전 볼륨이 남아 있다. 필요 없으면 지운다: docker volume rm initializer-stack_db.

브랜치를 바꾼 뒤 서버가 마이그레이션 오류로 뜨지 않는다

• 증상: 브랜치를 바꾸거나 main 을 받은 뒤 서버 · 테스트가 시작하다 멈춘다.

• 원인: DB 의 적용 기록과 마이그레이션 파일이 다르다. 도구마다 멈추는 경우가 다르다:

  경우	notes (node-pg-migrate)	activity (Flyway)	tags (Alembic)
  적용한 마이그레이션을 고쳤다	고친 내용을 무시하고 뜬다	Migration checksum mismatch for migration version 3	고친 내용을 무시하고 뜬다
  main 에도 같은 번호가 생겼다	main 의 것이 이름순으로 앞이면 Not run migration 0003_a is preceding already run migration 0003_b	Found more than one migration with version 3	Multiple head revisions are present
  적용한 마이그레이션이 없는 브랜치로 왔다	뜬다 (만든 표는 남는다)	뜬다 (만든 표는 남는다)	Can't locate revision identified by '0003'

• 해결:

  • 고쳤다: 되돌리고 바꿀 것을 새 번호로 더한다. notes · tags 도 같다. 오류는 없지만 이미 적용한 DB 에는 고친 내용이 들어가지 않아 DB 마다 스키마가 달라진다.
  • 번호가 겹쳤다: 내 것을 main 의 마지막 다음 번호로 바꾼다 (tags 는 revision · down_revision 도). 내 DB 에는 예전 번호가 기록돼 있으니 그 서버의 개발 · 테스트 DB 를 다시 만든다 → database.md.
  • 브랜치를 오갔다: 마이그레이션이 있는 브랜치로 돌아가면 그대로 쓴다. 이 브랜치에서 계속 쓰려면 그 서버의 DB 를 다시 만든다.

admin 의 vue-tsc · site 의 next build 가 TypeScript 7 에서 돌지 않는다

• 원인: 저장소 기본은 TypeScript 7 인데 vue-tsc 와 next build 는 TS 의 JS API 를 쓰고, TS 7 에는 아직 그 API 가 없다.
• 해결: 그 앱만 "typescript": "catalog:ts6".

Expo 패키지를 설치할 수 없다

• 증상: Expo 를 올리거나 npx expo install --fix 뒤 pnpm 이 너무 새 버전이라며 설치하지 않는다.
• 원인: pnpm 은 나온 지 하루가 안 된 버전을 설치하지 않는다(minimumReleaseAge).
• 해결: development.md 처럼 예외를 두지 않고 범위의 아래 끝을 그 전 버전으로 낮춘다.

zsh 에서 정리 명령이 통째로 멈춘다

• 증상: rm -rf clients/apps/*/dist 같은 명령이 no matches found 로 아무것도 하지 않는다.
• 원인: zsh 는 맞는 파일이 없는 * 를 만나면 명령 전체를 멈춘다.
• 해결: find 를 쓴다: find clients/apps -maxdepth 2 -name dist -type d -prune -exec rm -rf {} +.