기술 · 실용 가이드
Docker가 자격 증명 도우미를 찾지 못하나요? 설정·실행 파일·호출자를 먼저 추적하세요
어떤 Docker 설정이 어떤 docker-credential-* 프로그램을 골랐는지, 같은 사용자·WSL·sudo·서비스가 실행할 수 있는지 확인한 뒤 저장소를 바꾸세요.
이 오류는 손상된 비밀번호가 아니라 실행하지 못한 프로그램을 가리킵니다. Docker가 docker-credential-desktop이나 docker-credential-gcloud 같은 도우미를 선택했지만 Docker를 시작한 프로세스가 실행하지 못했습니다. config.json을 지우거나 credsStore를 틀리게 쓰면 호출을 숨길 수 있지만 의도한 보안 저장소도 꺼질 수 있습니다.
원본 파일을 보존하고 Docker가 실제로 읽은 설정과 대상 레지스트리 항목을 확인한 뒤 접미사를 docker-credential-<접미사>로 바꿔 생각합니다. 같은 사용자, 셸, sudo, WSL, 서비스 환경에서 보이는지 검사하고 입증한 경계만 수리합니다.
호출자와 유효한 설정을 고정하세요
실패한 정확한 명령과 레지스트리를 기록하고 whoami, HOME, DOCKER_CONFIG, 셸이나 서비스, sudo와 WSL 사용 여부를 확인합니다. 편집 전 config.json을 비공개로 백업하고 auth, 토큰, 도우미 출력을 로그에 넣지 마세요.
비밀이 아닌 선택 구조만 봅니다. 대상 레지스트리의 credHelpers를 먼저 보고 전역 credsStore를 확인합니다. root, 서비스 계정, 다른 Windows/WSL 사용자라면 그 호출자의 파일을 조사합니다.
설정 값을 하나의 실행 파일로 바꾸세요
credHelpers가 대상에 gcloud를 지정하면 docker-credential-gcloud, credsStore가 desktop이면 docker-credential-desktop이 대상입니다. 접미사는 Docker가 실행하는 실제 이름이지 추측한 패키지명이 아닙니다.
같은 호출 환경에서 command -v, type -a 또는 플랫폼 대응 명령으로 정확한 파일을 찾습니다. 없다면 오래된 Docker Desktop 연결과 의도적으로 설정한 독립 도우미를 구분한 뒤 설치나 링크를 검토합니다.
PATH 장애와 도우미 내부 장애를 나누세요
버전이나 목록처럼 비밀을 표시하지 않는 문서화된 점검을 실행합니다. 공식 get 시험이 반환하는 Secret은 민감 정보로 다루고 공유 로그에 저장하지 않습니다.
셸이 도우미를 시작하지 못하면 설치나 PATH를 고칩니다. 시작된 뒤 키체인, pass, gpg, Desktop 연결 또는 클라우드 인증 오류가 나오면 Docker 설정 변경을 멈추고 해당 도우미를 진단합니다.
입증한 최소 경계만 수리하세요
레지스트리 키나 접미사가 틀리면 좁은 설정 수정, 공식 도우미가 없으면 정확한 실행 파일 복원, 사용자·root·WSL·서비스가 다르면 실제 Docker 프로세스의 HOME, DOCKER_CONFIG, PATH 정렬이 필요합니다.
credsStore를 credStore로 바꾸는 영구 해결책은 쓰지 마세요. 후자는 유효한 저장소 키가 아니어서 무시됩니다. 다른 문서화된 인증 설계를 선택할 때만 저장소 설정을 삭제하거나 교체합니다.
원래 경로를 다시 시험하고 성공을 정의하세요
같은 셸, 서비스, CI 작업 또는 WSL 배포판을 새로 시작해 같은 레지스트리의 원래 Docker 명령을 실행합니다. 도우미 실행 오류가 사라지고 의도한 저장소에 도달하며 다른 사용자나 설정의 우연이 아니어야 성공입니다.
예상하지 못한 복사본이 선택되거나 설정이 곧 재생성되거나 sudo와 자동화에서만 재발하면 멈추고 호출자 목록을 다시 비교합니다. 소유자와 지원 도우미를 알기 전에는 자격 증명을 지우지 않습니다.
