React Hook Form 에러 메시지 표시 문제 해결: validation이 안 보일 때 체크리스트

required나 minLength를 넣었는데 errors 객체가 비어 있거나에러가 있는데 화면에 표시되지 않는 경우가 생깁니다.

validation이 안 보일 때는 에러가 없는지, 표시만 안 되는지 나눕니다

React Hook Form에서 에러 메시지가 안 보인다고 해서 항상 validation이 동작하지 않는 것은 아닙니다. errors 객체에는 값이 들어 있는데 화면 조건문이 잘못되어 표시만 안 될 수도 있고, input이 register에 연결되지 않아 validation 자체가 실행되지 않을 수도 있습니다. 먼저 개발 중에는 console.log(formState.errors)나 DevTools로 실제 errors가 생기는지 확인합니다. 이 한 단계만 거쳐도 문제 범위가 절반으로 줄어듭니다.

register가 input에 제대로 연결되어야 합니다

가장 흔한 원인은 input name과 register 이름이 맞지 않는 경우입니다. register(“email”)로 등록했는데 errors.userEmail을 보고 있으면 메시지는 나오지 않습니다. 커스텀 Input 컴포넌트를 쓸 때 ref나 {…register(“name”)}가 실제 input까지 전달되지 않는 경우도 있습니다. 겉으로는 입력창이 보이지만 React Hook Form 입장에서는 그 필드를 모르는 상태가 됩니다. 먼저 name, register, errors 경로가 같은지 확인합니다.

const { register, formState: { errors } } = useForm(); <input {...register('email', { required: '이메일을 입력해주세요' })} />
{errors.email?.message && <p>{errors.email.message}</p>}

validation rules는 submit 시점과 함께 봅니다

required, minLength, pattern 같은 rule을 넣어도 언제 검증할지 설정에 따라 보이는 타이밍이 달라집니다. 기본적으로 submit 이후에 에러가 보일 수 있고, mode를 나 onBlur로 바꾸면 입력 중에도 확인할 수 있습니다. 사용자가 입력하는 즉시 메시지가 보여야 하는 폼인지, 제출 버튼을 눌렀을 때만 보여도 되는 폼인지에 따라 mode를 정해야 합니다. 문제를 해결하려고 무작정 trigger를 넣기 전에 검증 타이밍을 먼저 봅니다.

errors는 객체 구조에 맞게 안전하게 출력합니다

에러 메시지를 출력할 때는 errors.email?.message처럼 optional chaining을 사용합니다. 중첩 필드나 배열 필드는 경로가 더 복잡해질 수 있습니다. 메시지가 undefined로 보인다면 rule에 message가 들어 있는지도 확인해야 합니다. required: “이메일을 입력해주세요”처럼 메시지를 직접 넣어야 화면에 원하는 문구를 출력할 수 있습니다. 에러 객체 구조와 UI 조건문이 서로 맞아야 validation 결과가 사용자에게 보입니다.

Controller를 쓰는 UI 라이브러리는 연결 방식이 다릅니다

MUI, React Select 같은 controlled component는 단순 register만으로 연결이 어색할 수 있습니다. 이때는 Controller로 value와 를 React Hook Form에 연결합니다. Controller를 쓰면서 field.onChange를 실제 컴포넌트에 넘기지 않으면 값이 폼 상태에 반영되지 않습니다. 최종 점검은 register 연결, rules, errors 경로, mode, Controller 연결 순서로 하면 됩니다.

발행 전 마지막 점검 기준

React Hook Form 에러 메시지 표시 문제 해결: validation이 안 보일 때 체크리스트은 문제 해결형 글이므로 독자가 바로 따라 할 수 있는 순서가 중요합니다. 증상부터 원인을 좁히고로컬에서 재현한 뒤, 설정과 버전 차이를 확인하는 흐름으로 마무리해야 합니다. 기존 글과 겹치는 설명은 길게 반복하지 않고, 현재 글에서는 어떤 기준으로 다음 행동을 선택할지 남기는 것이 좋습니다.

실제 발행 전에는 제목과 포커스 키워드가 너무 넓지 않은지, 본문 이미지가 문제 해결 흐름을 설명하는지, WordPress JSON의 카테고리와 Rank Math 포커스 키워드가 비어 있지 않은지 확인합니다. 이 점검까지 끝나야 단순 초안이 아니라 업로드 가능한 작성본으로 볼 수 있습니다.

실제 작업에서는 재현 조건을 먼저 고정합니다

React Hook Form 에러 메시지 표시 문제 해결: validation이 안 보일 때 체크리스트 같은 문제 해결형 글은 해결 명령어를 바로 나열하는 것보다 재현 조건을 고정하는 과정이 중요합니다. 같은 코드라도 로컬 개발 서버로컬 빌드, Preview 배포, Production 배포에서 다르게 동작할 수 있기 때문입니다. 독자는 먼저 어느 환경에서 문제가 나는지 표시하고같은 조건으로 다시 실행해본 뒤 원인을 좁혀야 합니다.

문제가 재현되는 조건을 적어두면 수정 후 검증도 쉬워집니다. 예를 들어 환경변수 문제라면 개발 서버 재시작 전후를 나눠 보고, 의존성 문제라면 node_modules를 지운 뒤 lockfile 기준으로 다시 설치합니다. 폼 validation 문제라면 submit 전과 submit 후의 errors 객체를 비교하고, 문제라면 브라우저 Network 탭에서 Origin과 응답 코드를 확인합니다.

또 하나 중요한 점은 임시 우회와 실제 해결을 구분하는 것입니다. 빌드 옵션을 끄거나 강제 설치 옵션을 쓰면 당장 지나갈 수는 있지만, 다음 배포에서 다시 막힐 수 있습니다. 글 본문에서는 빠른 확인 방법을 소개하되, 최종적으로는 설정과 버전을 맞추고 원인을 기록하는 쪽으로 안내해야 합니다.

같은 오류가 반복되지 않게 기록할 것

문제를 해결한 뒤에는 어떤 로그가 원인이었는지, 어떤 설정을 바꿨는지, 어떤 버전 기준으로 맞췄는지 남겨두는 것이 좋습니다. 팀 프로젝트라면 README나 작업 메모에 Node 버전, 패키지 매니저, 환경변수 이름, 배포 플랫폼 설정 위치를 적어두면 다음 사람이 같은 시간을 쓰지 않아도 됩니다.

블로그 글에서도 이 기록 방식이 중요합니다. 독자가 글을 읽고 단순히 “해결했다”에서 끝나는 것이 아니라, 다음에 같은 증상이 나오면 어디부터 확인해야 하는지 기억할 수 있어야 합니다. 그래서 마지막에는 증상, 확인 위치, 수정 방법, 재발 방지 기준을 짧게 다시 연결해주는 구성이 좋습니다.