왜 안 됐는지 콕 집어

KRDS CP-413 — 오류 상태에 대한 구체적인 오류 메시지를 제공하고 있다.

0. 들어가며 — “오류가 발생했습니다”만 뜨면

이번 533편은 오류 상태에 대한 구체적인 오류 메시지를 제공하라는 규칙입니다.

파일 업로드가 실패했을 때 — ‘오류가 발생했습니다’ 같은 막연한 메시지만 뜨면, 사용자는 무엇이 문제고 어떻게 고칠지 모르죠. CP-413은 무엇이 왜 잘못됐고 어떻게 해결하는지 구체적으로 알리라고 규정합니다. WCAG 3.3.1/3.3.3(오류 식별· 제안) 정신이죠. 이번 편을 풀어냅니다.

1. 원문 — 구체적 오류 메시지

CP-413 (컴포넌트 > 파일 업로드) “오류 상태에 대한 구체적인 오류 메시지를 제공하고 있다.”

파일 업로드 오류가 났을 때, 무엇이 왜 잘못됐고 어떻게 해결하는지 구체적인 오류 메시지를 제공하라는 뜻입니다.

정리: 파일 업로드 오류를 구체적으로 알려라. 이게 CP-413입니다.

2. 왜 구체적 오류 메시지인가

파일 업로드는 — 여러 이유로 실패할 수 있습니다: 형식 불일치, 크기 초과, 개수 초과, 손상된 파일, 네트워크 오류 등. 이 오류가 났을 때 — 사용자에게 무엇이 왜 잘못됐고 어떻게 고칠지를 구체적으로 알려야, 사용자가 문제를 해결하죠.

막연한 오류 메시지의 문제:

원인 불명 ‘오류가 발생했습니다’, ‘업로드 실패’ 같은 막연한 메시지는 무엇이 문제인지 안 알려줍니다. 사용자는 ‘왜 안 되지? 형식? 크기? 내 파일이 잘못됐나?’ 모르죠.

해결 불가 — 원인을 모르니 — 어떻게 고칠지도 모릅니다. 같은 파일을 다시 올려도 또 실패하고, 좌절해 포기 하죠.

반복 시행착오 — 추측하며 — 형식 바꾸고, 크기 줄이고 시도하지만 정확히 뭐가 문제인지 몰라 헤맵니다.

그래서 CP-413은 — 구체적인 오류 메시지를 제공하라고 합니다. 좋은 오류 메시지는 3가지를 담죠(WCAG 3.3.1 오류 식별, 3.3.3 오류 제안):

무엇이 (어느 파일) — 어느 파일이 문제인지(다중 업로드면). ‘○○.jpg 파일이…’

왜 (구체적 원인) — 무엇이 잘못됐는지 구체적으로:

형식 오류: ‘지원하지 않는 형식입니다(PDF, JPG, PNG만 가능).’

크기 초과: ‘파일이 너무 큽니다(최대 10MB, 현재 25MB).’

개수 초과: ‘최대 5개까지 올릴 수 있습니다.’

어떻게 (해결 방법) — 어떻게 고치는지 제안. ‘10MB 이하로 압축하거나 다른 파일을 선택하세요.’

막연한 ‘오류’가 아니라 —’○○.jpg는 25MB로 최대 10MB를 초과했습니다. 압축 후 다시 올려주세요’처럼 구체적이어야 사용자가 바로 해결하죠.

오류 위치·시점. 오류 메시지는 — 해당 파일·업로드 영역 근처에(어디가 문제인지 명확하게), 그리고 즉시 (파일 선택 시 검증해 바로) 보여줍니다. 제출 후 한참 뒤가 아니라 — 선택 즉시 알면 빨리 고치죠.

접근성. 오류 메시지는 스크린 리더에도 전달돼야 합니다(role="alert"/aria-live로 오류 발생 시 자동 안내). 색만으로(빨간 글자) 표시하지 말고 텍스트·아이콘으로도(색 무관, WCAG 1.4.1). 오류 필드와 메시지를 aria-describedby 로 연결하면 스크린 리더가 그 필드의 오류를 읽죠.

예방이 먼저(CP-408). 오류 메시지(사후)보다 — 제한 안내(CP-408, 사전)로 오류를 예방하는 게 먼저입니다. 하지만 — 그래도 오류가 나면, 구체적 메시지로 해결을 돕죠. 예방(408) + 구체적 오류(413)가 함께 갑니다.

이 규칙은 파일 업로드의 ’오류 해결 지원’을 담당합니다 — 무엇이 왜 잘못됐고 어떻게 고칠지 구체적으로 알려(413), 사용자가 오류를 스스로 해결하게 하죠. 막연한 오류로 좌절시키지 않습니다.

정리하면 — 막연한 오류 메시지는 원인·해결을 못 알려 사용자를 좌절시키므로, 어느 파일이 왜 잘못됐고 어떻게 고칠지 구체적으로 알리고 스크린 리더에도 전달해야 합니다.

3. 점검 / 개선

무엇을 점검하나

구체적 원인 — 오류 메시지가 무엇이 왜 잘못됐는지 구체적인가(막연한 ‘오류’ 아님).

해결 제안 — 어떻게 고칠지 제안하는가.

위치·접근성 — 해당 파일 근처에 즉시 표시되고, 스크린 리더·색 무관으로 전달되는가.

개선 방향

오류를 ‘무엇이/왜/어떻게’ 구체적으로(형식·크기·개수 등 원인 + 해결 방법).

해당 파일 근처 즉시 표시. role=“alert”/aria-live, 색 외 표시(WCAG 3.3.1/3.3.3/1.4.1).

4. 누가 담당하나 / 우리 사이트에 해당될까?

역할	책임
콘텐츠/UX	구체적 오류 문구 작성
퍼블리셔/개발	오류 검증·메시지·접근성 구현

기관 유형	CP-413 적용
중앙행정기관(대표·운영) / 공공기관 / 지자체	✅ 필수 (파일 업로드 사용 시)

파일 업로드를 쓰는 모든 사이트가 해당됩니다.

5. 30초 자가진단 + FAQ

✅ 30초 자가진단

□ 오류 메시지가 무엇이 왜 잘못됐는지 구체적인가요(막연한 ‘오류’ 아님)?

□ 어떻게 고칠지 제안하나요?

□ 해당 파일 근처에 즉시 표시되고, 스크린 리더·색 무관으로 전달되나요?

❓ FAQ

Q1. ’오류가 발생했습니다’면 안 되나요? 무엇이 문제인지 안 알려줘 사용자가 해결 못 합니다. ’25MB로 최대 10MB 초과, 압축 후 재시도’처럼 구체적으로요. Q2. 오류 메시지를 어디에 보여주나요? 해당 파일·업로드 영역 근처에, 파일 선택 시 즉시 보여줍니다. 제출 후 한참 뒤보다 빨리 고치죠. Q3. CP-408(제한 안내)과 관계가 있나요? 예방(408 사전 안내)이 먼저고, 그래도 오류 나면 구체적 메시지(413)로 해결을 돕습니다. 함께 가죠.

6. 마무리

CP-413의 메시지:

왜 안 됐는지 콕 집어 — 무엇이 왜 잘못됐고 어떻게 고칠지 구체적으로 알려라.

막연한 오류는 원인·해결을 못 알려 사용자를 좌절시킵니다. 어느 파일이 왜 잘못됐고 어떻게 고칠지 구체적으로 알리고 스크린 리더에도 전달하는 게 핵심이죠. 다음 편은 파일명 한 줄 표시입니다.

다음 편 예고 ▶ 「534. (CP-414) 업로드된 파일 이름 텍스트를 한 줄로 제공하고 있다.」

ViewCheck는 파일 업로드 오류 메시지가 구체적인지를 진단합니다.

📚 참고 출처

KRDS 컴포넌트 — 파일 업로드(File upload) 가이드 — https://www.krds.go.kr/html/site/component/component_41.html

WCAG 2.1 SC 3.3.1 Error Identification — https://www.w3.org/WAI/WCAG21/Understanding/error-identification.html

KRDS #ViewCheck #공공웹사이트 #전자정부 #디지털정부 #웹접근성 #디자인시스템 #UIUX #UI컴포넌트 #웹표준

KRDS,ViewCheck,공공웹사이트,전자정부,디지털정부,웹접근성,디자인시스템,UIUX,UI컴포넌트,웹표준