auth/user-not-found

의미

auth/user-not-found는 제공된 식별자에 대응하는 기존 사용자 레코드가 없음을 뜻합니다.

확인

1. 현재 화면 또는 로그에 표시된 오류 코드를 확인합니다.
2. 해당 문자열이 auth/user-not-found와 일치하는지 비교합니다.
3. 사용자 조회·토큰 검증·비밀번호 재설정 중 어느 인증 흐름에서 발생했는지와 요청 시각을 기록합니다.
4. 배포 환경의 Firebase project ID와 요청한 식별자 유형(UID·이메일·전화번호)을 비밀값 없이 기록해 예상한 환경과 비교합니다.

재확인과 주의

같은 환경에서 해당 식별자 유형으로 사용자 조회를 한 번만 재현해 오류 코드가 유지되는지 확인합니다. 오류만 보고 사용자 계정을 자동 생성·삭제·복구하지 마세요. 이메일 주소, 전화번호, ID 토큰 등 개인정보와 인증값을 로그·이슈·문의에 기록하지 않습니다.

출처

• Firebase Admin Authentication API Errors (새 창에서 열림)

관찰값 기록

문제가 발생한 URL 또는 화면, 표시 시각, 운영 환경과 최근 변경 사항을 먼저 기록합니다. 화면이나 로그에 오류 문구가 일부만 보이면 앞뒤 문장을 보존하고 비밀번호·토큰·쿠키·개인정보는 가립니다.

다음 항목을 실제 값과 함께 확인합니다.

1. 현재 화면 또는 로그의 오류 코드가 auth/user-not-found와 정확히 일치하는지 확인합니다.
2. 오류 코드가 일치하면 제공된 식별자에 대응하는 기존 사용자 레코드가 없다는 공식 설명과 대조합니다.
3. 사용자 조회·토큰 검증·비밀번호 재설정 중 어느 인증 흐름에서 발생했는지와 요청 시각을 기록합니다.
4. 배포 환경의 Firebase project ID와 요청한 식별자 유형(UID·이메일·전화번호)을 비밀값 없이 기록해 예상한 환경과 비교합니다.
5. 같은 환경에서 해당 식별자 유형으로 사용자 조회를 한 번만 재현해 오류 코드가 유지되는지 확인합니다.

판정 기준

오류 문구가 일치해도 같은 원인이 확정되는 것은 아닙니다. 웹서버·런타임·운영체제·플랫폼과 최근 변경 사항을 비교하고, 기대한 관찰값이 나오지 않으면 다음 단계로 넘어가지 않습니다. 이 문서는 출처가 확인한 범위만 설명하며, 범위를 벗어난 원인과 조치는 단정하지 않습니다.

안전한 다음 확인

설정·권한·데이터를 변경하기 전에 백업과 되돌리기 방법을 기록합니다. 운영 환경의 방화벽 전체 해제, 인증서 검증 우회, 데이터 삭제, 비밀값 공개를 기본 조치로 사용하지 않습니다. 확인 결과가 문서의 조건과 다르면 관련 Platform·Component 문서와 공식 출처를 먼저 확인합니다.

원인 분포

[Observation] 수집된 3건에서는 다음 원인이 각각 1건씩 관측되었습니다.

원인 유형	관측 사례 수
회원 생성 완료 전 로그인 요청 실행	1건
로컬 Authentication 에뮬레이터와 운영 프로젝트의 사용자 저장소 불일치	1건
getUser()의 모든 실패를 사용자 미존재로 처리	1건

[Observation] 위 분포는 관측된 사례 기준이며 실제 발생 빈도를 의미하지 않습니다.

오진 함정

• [Observation] Firebase Console에 사용자가 표시되어도 로컬 Authentication 에뮬레이터가 다른 사용자 저장소를 사용하면 로컬 getUser()는 auth/user-not-found를 반환할 수 있습니다.
• [Observation] getUser()의 모든 오류를 사용자 미존재로 간주해 createUser()를 호출하면 이미 존재하는 UID 오류가 뒤따를 수 있습니다.
• [Observation] 회원 생성과 로그인 요청의 실행 순서를 확인하지 않으면 생성 완료 전 조회로 인해 auth/user-not-found가 발생할 수 있습니다.

환경 매트릭스

실행 환경 및 흐름	관측된 조건	결과 또는 수정
회원 생성 직후 로그인	생성 Promise 완료 전 로그인 실행	생성 완료 후 로그인하거나 생성 시 자동 로그인
로컬 에뮬레이터에서 Admin SDK 사용	로컬 Authentication 에뮬레이터와 운영 프로젝트의 저장소가 다름	Functions만 실행하도록 에뮬레이터 명령 변경
Admin SDK getUser() 실패 후 생성	모든 오류를 사용자 미존재로 처리	auth/user-not-found만 생성 처리하고 다른 오류는 별도 처리

진단 순서

1. [Observation] 오류가 발생한 호출이 회원 생성 완료 전 실행되었는지 확인합니다.
2. [Observation] 로컬 에뮬레이터를 사용한다면 호출 대상이 운영 프로젝트인지 로컬 Authentication 에뮬레이터인지 확인하고 사용자 저장소를 구분합니다.
3. [Observation] Admin SDK getUser()의 오류 코드가 실제로 auth/user-not-found인지 확인합니다.
4. [Observation] auth/user-not-found가 아닌 오류를 사용자 미존재로 처리해 createUser()를 재호출하고 있지 않은지 확인합니다.
5. [Observation] 확인 결과에 따라 생성 완료 후 로그인, 에뮬레이터 실행 범위 변경, 오류 코드별 분기를 적용합니다.