주제별 글 모음

개발 환경·도구·기타 언어 문제 해결

개발하다가 에러 메시지에서 막혔을 때 원인과 해결 순서를 찾기 위한 글입니다. git push 거부, SSH 키 권한 오류, docker.sock 권한, apt lock, pip의 externally-managed-environment, npm ERESOLVE처럼 검색으로 자주 찾는 오류를 다룹니다.

우분투 설정(고정 IP, NVIDIA 드라이버), WSL2 설치, PATH 설정, 포트 사용 중 확인, Kubernetes Pod 문제 진단도 포함합니다. 명령은 가능한 한 실제로 실행해 본 출력과 대조했습니다.

Go의 context, Rust 소유권 에러, JavaScript 비동기 디버깅, JSON 직렬화 문제 같은 C++ 밖의 언어 글도 여기에 있습니다.

처음 읽기 좋은 글

• git push rejected 해결: fetch first·non-fast-forward·refusing to merge unrelated histories·divergent branchesgit push가 (fetch first), (non-fast-forward)로 거부되는 이유와 merge·rebase 해결 순서, unrelated histories, divergent branches 설정, force-with-lease, GH006 보호 브랜치까지 다룹니다.
• 도커 permission denied /var/run/docker.sock 오류 해결: docker 그룹 추가와 재로그인, chmod 666을 쓰면 안 되는 이유리눅스에서 docker 명령이 /var/run/docker.sock permission denied로 실패할 때 원인을 확인하고 docker 그룹 추가, 재로그인, rootless Docker, snap·Docker Desktop·CI·소켓 마운트 환경별 해결법을 정리합니다.
• pip install 오류 error: externally-managed-environment 해결 방법 (우분투 24.04·데비안 12·맥 Homebrew)우분투 23.04 이상, 데비안 12, 맥 Homebrew Python에서 pip install이 externally-managed-environment로 막히는 이유(PEP 668)와 venv·pipx·apt·uv 해결 순서, --break-system-packages를 써도 되는 경우, Docker·cron·VS Code·sudo pip 문제까지 설명합니다.

전체 글 50편

각 글에 표시된 난이도를 기준으로 초급, 중급, 고급 순으로 나눴습니다. 처음이라면 위쪽부터 읽고, 이미 아는 단계는 건너뛰어도 됩니다.

초급 (21편)

• 개발 환경에서 자주 막히는 에러 응급처치표: pip, git, apt, MySQL, CUDA, CORS, KubernetesModuleNotFoundError, git push rejected, 한글 파일명 깨짐, apt lock, MySQL root 접속, CUDA, CORS, Kubernetes Pod 같은 흔한 개발 환경 에러를 증상별로 정리하고 git과 파이썬은 컨테이너에서 재현해 확인했습니다.
• 깃허브 SSH 키 등록 방법과 Permission denied (publickey) 해결: 윈도우·맥·리눅스ssh-keygen -t ed25519로 키를 만들고 깃허브에 등록해 ssh -T로 확인하는 과정을 윈도우·macOS·리눅스별로 설명하고, Permission denied (publickey), Host key verification failed, 호스트 키 변경 경고, 22번 포트 차단, 계정 두 개 설정까지 다룹니다.
• 도커 permission denied /var/run/docker.sock 오류 해결: docker 그룹 추가와 재로그인, chmod 666을 쓰면 안 되는 이유리눅스에서 docker 명령이 /var/run/docker.sock permission denied로 실패할 때 원인을 확인하고 docker 그룹 추가, 재로그인, rootless Docker, snap·Docker Desktop·CI·소켓 마운트 환경별 해결법을 정리합니다.
• 맥·우분투 터미널 유틸 추천: ripgrep, fd, bat, fzf, tmux 설치와 이름 함정ripgrep, fd, bat, fzf, jq, tmux, zoxide, eza, btop을 우분투 24.04 컨테이너에서 설치해 실제 버전과 명령 이름을 확인했습니다. 우분투에서는 fd가 fdfind, bat가 batcat으로 설치되는 점, ripgrep과 grep의 속도 비교 결과, 맥 Homebrew 이름을 함께 정리합니다.
• 바이브 코딩을 제대로 쓰는 법: Cursor·Copilot·Claude의 컨텍스트 수집과 검증 습관Cursor·Copilot·Claude 같은 AI 코딩 도구가 LSP와 FIM 완성 모델, 컨텍스트 수집 파이프라인으로 어떻게 제안을 만드는지 살펴보고, 그 구조를 알면 프롬프트와 결과 검증 습관을 어떻게 바꿔야 하는지 설명합니다.
• 우분투 설치 후 개발자가 처음 할 일: 드라이버·한글 입력·개발 도구·Docker·런타임 초기 세팅우분투 24.04 LTS를 새로 설치한 개발자를 위한 첫날 체크리스트. 드라이버·한글 입력·필수 CLI 도구·버전 관리자(nvm, uv)·Docker 권한 설정·에디터·snap/flatpak 선택 기준·보안 설정까지 이유와 함께 순서대로 정리합니다.
• 우분투 터미널 vim 설정: vim-tiny에서 .vimrc 적용까지 직접 확인한 순서우분투 24.04 컨테이너에서 vi가 가리키는 실제 프로그램, vim-tiny와 vim 패키지의 기능 차이(syntax, clipboard), 최소 .vimrc의 설정이 실제로 적용되는지를 직접 실행해 확인한 결과와, 터미널 개발에 쓰는 기본 설정을 정리합니다.
• 우분투 apt Could not get lock /var/lib/dpkg/lock-frontend 해결: unattended-upgr 대기와 dpkg was interrupted 복구우분투 22.04·24.04에서 apt의 Could not get lock, Unable to acquire the dpkg frontend lock 오류 원인과 잠금 프로세스 확인, 자동 업데이트 대기·중지, dpkg was interrupted 복구 순서를 다룹니다.
• 우분투 MySQL 설치 후 root 접속 안 됨: ERROR 1045 Access denied와 auth_socket, 원격 접속 설정우분투 22.04/24.04에 apt로 MySQL 8.0을 설치한 직후 mysql -u root -p가 ERROR 1045로 막히는 이유(auth_socket), mysql_secure_installation 무한 반복 오류, 앱 전용 계정 생성, 원격 접속과 ERROR 2002 해결을 설명합니다.
• 윈도우 11/10에 WSL2 우분투 설치하기: wsl --install 오류 코드 해결과 설치 직후 바꿀 설정wsl --install로 WSL2 우분투를 설치하는 순서, 0x80370102·0x8007019e·0x800701bc 오류 해결, 비밀번호 분실 시 복구, .wslconfig 메모리·mirrored 네트워크, systemd, 다른 드라이브로 옮기는 법까지 정리합니다.
• 윈도우 PATH 환경 변수 설정법: '내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다' 해결윈도우 11/10에서 PATH 환경 변수를 추가하는 방법과, cmd의 '내부 또는 외부 명령이 아닙니다', PowerShell의 'is not recognized' 오류가 나는 원인을 사용자·시스템 변수 순서, setx 함정, 앱 실행 별칭까지 정리합니다.
• 포트 사용 중 확인하고 종료하는 법: EADDRINUSE·Address already in use 해결 (윈도우·리눅스·맥)3000·8080·5000 포트가 이미 사용 중이라 서버가 안 뜰 때, 윈도우 netstat·Get-NetTCPConnection, 리눅스 ss·lsof·fuser, 맥 lsof로 점유 프로세스를 찾아 종료하는 법과 프로세스가 안 보이는 경우(Hyper-V 예약 포트, AirPlay, Docker)를 정리합니다.
• 혼자 만들고 배포하는 개발자의 체크리스트: Cloudflare Pages 배포, 패키징 자동화, 검증 습관, 채용 시장 읽기사이드 프로젝트를 만들고 배포하며 정리한 순서입니다. 정적 사이트 배포, 릴리스 패키징 자동화, 단계별 검증 규칙, 그리고 AI 시대 채용 시장을 읽는 관점을 실제로 쓴 글들과 연결해 정리했습니다.
• AI 시대 개발자 채용 시장 읽는 법: 신입 공고 감소, 통계가 말하는 것과 말하지 않는 것스탠퍼드 디지털 이코노미 랩의 연구, 한국노동연구원 보고서를 인용한 보도, Indeed 채용 공고 지수를 직접 읽고 정리했습니다. 22~25세 개발자 고용 감소, 신입 공고 비중 하락이 무엇을 뜻하고 무엇은 아직 모르는지, 취준생과 주니어가 할 수 있는 준비를 구분해 적습니다.
• git push rejected 해결: fetch first·non-fast-forward·refusing to merge unrelated histories·divergent branchesgit push가 (fetch first), (non-fast-forward)로 거부되는 이유와 merge·rebase 해결 순서, unrelated histories, divergent branches 설정, force-with-lease, GH006 보호 브랜치까지 다룹니다.
• ModuleNotFoundError: No module named 해결: pip install 했는데 모듈이 없다고 나올 때 (윈도우·맥·리눅스)pip install로 설치했는데 ModuleNotFoundError가 나는 가장 흔한 이유는 pip와 python이 서로 다른 인터프리터를 가리키기 때문입니다. python -m pip, sys.executable, venv 활성화 오류, VS Code·Jupyter 인터프리터, cv2·sklearn 같은 이름 차이, 상대 import 오류를 순서대로 확인합니다.
• npm install -g 권한 오류 EACCES: permission denied 해결 (우분투·맥, sudo 없이)npm install -g가 EACCES: permission denied, mkdir /usr/local/lib/node_modules로 실패하는 이유와, sudo 대신 nvm 또는 npm prefix 변경으로 해결하는 방법, root 소유가 된 ~/.npm 캐시 복구, npx 활용, 윈도우 EPERM까지 다룹니다.
• npm install 에러 해결 10가지: EACCES, ENOSPC, Timeout, peer dependencynpm install이 EACCES, ENOSPC, ERR_SOCKET_TIMEOUT, peer dependency 충돌, ERESOLVE, 404, node-gyp 빌드 실패, 캐시 손상, lock 파일 충돌, Windows 경로 길이 제한으로 실패할 때 원인별 해결책을 정리합니다.
• nvm으로 Node.js 버전 변경하기: 윈도우(nvm-windows)·맥·리눅스 설치와 nvm 인식 안 됨 오류 해결윈도우용 nvm-windows와 맥·리눅스용 nvm-sh는 별개 프로그램입니다. 설치, nvm use로 Node 버전 바꾸기, .nvmrc, nvm is not recognized·exit status 1·command not found 오류와 전역 패키지가 사라지는 이유를 설명합니다.
• pip install 오류 error: externally-managed-environment 해결 방법 (우분투 24.04·데비안 12·맥 Homebrew)우분투 23.04 이상, 데비안 12, 맥 Homebrew Python에서 pip install이 externally-managed-environment로 막히는 이유(PEP 668)와 venv·pipx·apt·uv 해결 순서, --break-system-packages를 써도 되는 경우, Docker·cron·VS Code·sudo pip 문제까지 설명합니다.
• Vim이 안 꺼질 때부터 시작하는 Vi/Vim: 종료, 모드, 이동, 편집, 검색·치환서버에서 Vim을 열었다가 빠져나오지 못하는 상황부터 시작해 상황별 종료 명령, Vi와 Vim의 차이, 노멀·입력·비주얼·명령 모드, hjkl과 단어·화면 단위 이동, 삭제와 변경, 검색·치환, 복사·붙여넣기까지 서버 작업에 필요한 기본기를 다룹니다.

중급 (26편)

• 릴리스 패키징 자동화: 모듈별 빌드·취합·압축에서 시간과 실수를 줄이는 방법사람이 모듈마다 빌드해 모아서 압축하는 수동 패키징을 릴리스 매니페스트, 빌드 전 버전 검사, 병렬 빌드와 캐시, 재현 가능한 압축으로 자동화하는 방법입니다. 12개 모듈 데모로 직렬 20.9초가 병렬 9.7초, 변경 없을 때 0초로 줄고 버전 불일치를 빌드 전에 잡는 과정을 실행 결과로 보여줍니다.
• 메모리 누수 찾기: 프로파일러 선택과 재현 시나리오 | Valgrind·ASan·Heaptrack메모리가 계속 늘어나는 서비스에서 C++는 ASan·LSan, Valgrind, Heaptrack, Python은 tracemalloc과 memory_profiler, Node.js는 힙 스냅샷으로 누수를 찾는 방법을 보여줍니다. 재현 시나리오를 문서화하는 법과 누수와 단편화의 구분도 다룹니다.
• 바이브 코딩 작업 규칙: shrinkto.app을 3일 만에 만들며 지킨 8가지AI 코딩 도구와 함께 shrinkto.app을 3일간 만들며 프로젝트 지침 파일에 적어 둔 규칙을 정리했습니다. 단계별 승인, API 추측 금지, 스파이크로 먼저 검증, 출력 파일 내용까지 보는 테스트 등 결과물이 무너지지 않게 한 규칙과 그 이유를 설명합니다.
• 실시간 서버 만들기 전에 알아 둘 네트워크 기본: TIME_WAIT, select와 epoll, WebSocket·SSE, 채팅 서버 구조2,000번 연결·종료 뒤 TIME_WAIT 소켓 수, select의 파일 디스크립터 1,024 제한, epoll 등록 성공을 컨테이너에서 직접 확인하고 연결 상태, I/O 멀티플렉싱, 전송 방식 선택, 채팅 서버 구조 글로 이어서 읽는 순서를 제안합니다.
• 알고리즘 최적화 실전 사례 | 코딩테스트 시간 초과(TLE) 해결기중복 제거, 구간 합, 최단 경로, 부분합, 문자열 매칭의 TLE 코드를 복잡도 관점에서 고친 사례와 Big-O·상각 분석, 공간-시간 트레이드오프, 캐시·분기 예측까지 정리합니다.
• 우분투 24.04 고정 IP 설정: netplan(서버)과 nmcli·설정 앱(데스크톱), 적용 안 될 때 해결우분투 24.04에서 고정 IP를 설정하는 방법을 서버(netplan + networkd)와 데스크톱(NetworkManager)으로 나눠 설명합니다. gateway4 경고, 권한 경고, cloud-init 덮어쓰기, netplan try 롤백, DNS 확인까지 다룹니다.
• 우분투 24.04 NVIDIA 드라이버 설치와 오류 해결: nvidia-smi 실패, 검은 화면, Secure Boot MOK우분투 24.04에 NVIDIA 그래픽 드라이버를 ubuntu-drivers와 apt로 설치하는 방법, open 모듈 선택, Secure Boot MOK 등록, nvidia-smi 통신 실패·로그인 루프·dpkg 충돌·커널 업데이트 후 오류 해결과 완전 삭제까지 설명합니다.
• 우분투 로봇 현장 디버깅: SSH 접속, 유선랜 직결, 로그·CPU·네트워크 상태 점검 명령현장에서 우분투 로봇에 유선랜을 직결하고 SSH로 접속해 로그, CPU·메모리·디스크, 네트워크, ROS 2 상태를 확인하는 순서와 명령을 정리했습니다. 컨테이너에서 직접 실행해 본 출력과 상태 점검 스크립트, 그리고 실제 로봇에서는 확인하지 못한 부분을 구분해 적었습니다.
• 우분투 원격 데스크톱(xrdp) 설정: 접속 불능을 피하려고 확인할 것들우분투 24.04에 xrdp를 설치하면 생기는 설정 파일(xrdp.ini, sesman.ini, startwm.sh), 기본 포트와 보안 옵션, 권장 패키지를 컨테이너에서 확인했습니다. 설정을 바꾸다 원격 접속이 막히는 일을 피하려는 백업·SSH 보험·테스트 순서를 정리하고, 확인하지 못한 부분은 구분해 적었습니다.
• 우분투에서 kitty 터미널 사용하는 개발자 팁 | 설치·설정·SSH terminfo 해결까지우분투에서 kitty 터미널을 apt 또는 공식 스크립트로 설치하고 kitty.conf, Nerd Font, 테마, 레이아웃을 설정하는 방법과, SSH 접속 시 xterm-kitty terminfo 오류를 ssh kitten이나 수동 복사로 해결하는 과정을 다룹니다.
• 효율적인 디버깅 팁 — 빠르고 정확하게 버그를 잡는 사고방식간헐적 버그를 재현 가능한 상태로 만드는 법, 가설을 세우고 검증하는 순서, 코드·커밋·데이터·설정 범위에 이분 탐색을 적용하는 방법을 다룹니다. 스택 트레이스와 에러 메시지 읽는 법, 로그와 디버거 중 무엇을 쓸지 고르는 기준, 프로덕션 디버깅의 차이도 설명합니다.
• Cloudflare Pages 배포: GitHub 연동, Wrangler CLI, Pages Functions와 Vercel·Netlify 비교Cloudflare Pages 배포를 GitHub 연동·Wrangler·Functions부터 정리하고, Pages와 Workers 정적 자산 중 무엇을 고를지, _redirects 개수 한도와 _headers 병합, apex 도메인 조건, 파일 수 제한 같은 운영 함정까지 다룹니다.
• Eclipse Paho MQTT C 라이브러리: MQTTClient와 MQTTAsync, 콜백 스레드, 재접속, Last WilllibVDA5050++가 paho.mqtt.cpp를 거쳐 감싸는 Eclipse Paho MQTT C 라이브러리를 정리합니다. 라이브러리 4종과 빌드 옵션, 동기 MQTTClient와 비동기 MQTTAsync의 차이, 콜백이 도는 스레드와 메시지 해제 규칙, 접속 옵션 기본값, 자동 재접속과 재구독, 끊긴 동안의 발행, 영속성, TLS, 디버깅까지 VDA5050 로봇 클라이언트 예제로 다룹니다.
• Git 머지 충돌 해결 예제 | 장기 리팩토링 브랜치를 main에 병합하는 순서몇 달 동안 main과 따로 진행된 리팩토링 브랜치를 병합할 때 충돌이 쏟아지는 상황을 예제로, main을 리팩토링 브랜치로 역방향 머지하고 git status --porcelain 코드로 충돌을 분류한 뒤 기계적인 충돌과 로직 충돌을 나눠 푸는 방법, --ours와 -X ours의 차이, rerere·zdiff3·remerge-diff 활용법을 설명합니다.
• git 한글 깨짐 해결: git status 한글 파일명 \354\225\210, 커밋 메시지·diff 깨짐 원인별 정리git status에 한글 파일명이 \354\225\210처럼 나오는 core.quotepath, 윈도우 PowerShell 코드페이지, git log 커밋 메시지 깨짐, macOS NFD 파일명, CP949 파일 diff 깨짐을 증상별로 구분해 고칩니다.
• Git rebase interactive 사용법 | pick·squash·fixup·충돌 해결·실수 복구PR을 올리기 전 지저분한 커밋을 git rebase -i로 정리하는 방법을 pick, squash, fixup, reword, edit 명령별로 보여줍니다. autosquash와 git add -p로 큰 커밋을 쪼개는 법, 리베이스 중 충돌 해결과 reflog 복구도 다룹니다.
• Go context로 타임아웃·취소 처리하기: WithTimeout, WithCancel, HTTP 서버 종료Go의 context.WithTimeout으로 DB와 외부 API 호출에 상한을 걸고, WithCancel로 한 단계가 실패하면 나머지 워커를 멈추고, HTTP 서버에서 요청 컨텍스트와 Shutdown 컨텍스트를 따로 쓰는 방법을 코드로 보여줍니다. 세 API의 선택 기준도 다룹니다.
• JavaScript 비동기 디버깅 예제 | Unhandled Rejection과 Promise 체인 에러 추적하기간헐적으로 Unhandled Rejection만 남는 Node.js·Express 코드를 예로, 에러 핸들러가 빠진 Promise 체인에서 에러가 왜 사라지는지 재현하고, 비동기 스택 트레이스로 호출 위치를 찾는 조건, async/await 전환, 전역 핸들러, Express 에러 미들웨어, Sentry 연동, 타임아웃·재시도 패턴까지 설명합니다.
• JSON 직렬화에서 데이터가 사라지는 경우: Date·BigInt·순환 참조, 검증, 대용량 성능JSON.stringify/parse, json.dumps/loads부터 Date·BigInt·순환 참조 데이터 손실, Zod/Pydantic 검증, 대용량 페이로드 성능까지 언어 무관으로 정리한 직렬화 가이드.
• Kubernetes Pod가 안 뜰 때: CrashLoopBackOff·ImagePullBackOff·Pending 원인 찾기Kubernetes Pod 트러블슈팅. CrashLoopBackOff, ImagePullBackOff, Pending 상태의 흔한 원인과 kubectl logs·describe·events로 원인을 찾는 순서, 원인별 해결 방법을 정리합니다.
• Linux 디스크 full vs inode full 해결 순서 | 용량·아이노드 트러블슈팅“No space left on device”가 떴을 때 df -h와 df -i로 블록 부족과 inode 고갈을 먼저 구분하고, 큰 디렉터리·작은 파일이 몰린 경로·Docker 잔여물·삭제됐지만 열려 있는 파일(lsof +L1)을 차례로 찾아 정리하는 순서를 다룹니다.
• npm ERR! ERESOLVE unable to resolve dependency tree 해결: peer dependency 충돌 읽는 법과 --legacy-peer-deps 대신 할 일npm install이 ERESOLVE unable to resolve dependency tree로 실패할 때 Found·peer 줄 읽는 법과 업그레이드, 호환 버전, overrides, --legacy-peer-deps, --force 순의 해결법과 위험을 설명합니다.
• Rust 소유권 에러 예제: cannot move out·cannot borrow as mutable·조건부 반환 빌림과 수명 에러 해결cannot move out of borrowed content(E0507), cannot borrow as mutable more than once(E0499), 조건부로 참조를 반환할 때의 E0502, 지역 변수 참조 반환(E0515), 스레드 클로저의 E0373 같은 Rust 소유권 에러를 문제 코드와 컴파일러 메시지로 재현하고, 원인과 해결 코드를 예제별로 보여 줍니다.
• shrinkto.app 만든 과정: 브라우저에서 목표 용량에 맞춰 영상·이미지를 줄이는 도구파일을 서버에 올리지 않고 브라우저 안에서 영상·이미지를 목표 용량(MB)에 맞춰 줄이는 shrinkto.app을 만든 과정입니다. WebCodecs와 mediabunny, ffmpeg.wasm 폴백, frameRate 미지정 시 2배 오버슈트, 25MiB 파일 한도 같은 실제 부딪힌 문제와 해결, 개발 기록을 정리했습니다.
• ssh: connect to host port 22: Connection refused 해결: 우분투 24.04 SSH 연결 거부 원인별 점검SSH Connection refused와 timed out, No route to host의 차이를 구분하고 우분투 24.04 기준 openssh-server 설치, ssh.socket 포트 변경, ufw, WSL2·VM, 보안 그룹, fail2ban을 순서대로 점검합니다.
• torch.cuda.is_available() False 해결: CPU 버전 PyTorch, 드라이버, WSL2, no kernel image 오류GPU가 있는데 torch.cuda.is_available()이 False일 때 torch.__version__의 +cpu 접미사, torch.version.cuda, nvidia-smi의 CUDA Version 의미를 확인하고, 올바른 --index-url로 재설치하는 법과 WSL2·conda 혼용·no kernel image 오류까지 설명합니다.

고급 (3편)

• 컨테이너 오케스트레이션 심화 — 스케줄러·DNS·CNI·스토리지·프로덕션 패턴Kubernetes·Docker Swarm 내부를 깊이 있게 다룹니다. 스케줄링 프레임워크, CoreDNS·서비스 디스커버리, Flannel·Calico 오버레이, PV/PVC·StorageClass, PDB·토폴로지 분산 등 운영 관점까지.
• Core Dump로 크래시 원인 찾기: 생성 설정, GDB 분석, 프로덕션 수집 자동화Core Dump 생성 설정과 GDB 분석, Segmentation Fault 디버깅을 정리합니다. Ubuntu apport·systemd-coredump가 코어를 가져가는 위치, Docker·Kubernetes에서 core_pattern이 호스트 전역인 문제, debuginfod와 분리 심볼, 코어에 남는 비밀 정보까지 프로덕션 기준으로 다룹니다.
• Docker 네트워킹 내부 — CNI·veth·브리지·iptables·서비스 디스커버리Docker·Kubernetes 네트워크 내부: CNI와 libnetwork, veth·Linux bridge, 포트 매핑 iptables/nft, DNS·서비스 디스커버리, 프로덕션 패턴까지 실무 심화 정리.