8. Errors

Alert

이 글은 Claude Code의 도움을 받아 작성되었습니다

TL;DR

• Go에는 try/except 같은 예외 구문이 없고, 함수가 에러를 값으로 반환해 호출자가 if err != nil로 확인하는 방식
• error는 Error() string 하나만 가진 인터페이스이고, nil이 인터페이스의 zero value라 “에러 없음 = nil”이 성립
• 에러 생성은 errors.New와 포매팅용 fmt.Errorf, 반환은 (결과, error) 다중 반환 관용구
• 센티넬 오류는 미리 정의한 대표 에러 값이며, 문자열 비교 대신 errors.Is로 종류를 구분
• %w로 문맥을 덧붙여 래핑하면 원본이 보존되고, errors.Is(값 비교)·errors.As(타입 확인 후 추출)로 체인을 검사
• panic/recover는 호출자가 정상 처리할 수 없는 치명적 상황 전용이며, 일상 흐름 제어용이 아님

Python에서 에러는 예외(exception)다. 함수 어디서든 raise로 던지고, 호출 흐름 어딘가의 try/except가 받는다. 받지 못하면 프로그램이 죽는다. 던지는 쪽과 받는 쪽이 코드상 떨어져 있어도 동작하는 게 예외의 장점이자, 흐름이 어디로 튀는지 알기 어려운 단점이다.

Go는 정반대로 설계됐다. 에러를 던지는 특별한 구문이 없다. 함수는 에러를 값으로 반환하고, 호출자는 그 값을 매번 손으로 확인한다. “errors are values”(에러는 값이다)라는 한 줄이 Go 에러 처리 철학의 전부다. 던지고 받는 마법 대신, 반환값으로 주고받는 평범한 데이터로 다룬다. 이 글은 Python의 예외에 익숙한 개발자가 Go의 이 방식을 처음 만났을 때 헷갈리는 지점을 정리한다.

---

1. error는 인터페이스다

Go에서 error는 특별한 키워드가 아니라 내장 인터페이스다. 정의는 이게 전부다.

type error interface {
    Error() string
}

Error() string 메서드 하나만 구현하면 어떤 타입이든 에러가 된다. 07편에서 다룬 대로 Go 인터페이스는 메서드 집합만 만족하면 자동으로 충족되므로, 별도 상속이나 등록 없이도 내 타입을 에러로 쓸 수 있다.

type MyError struct {
    Code int
}
 
func (e MyError) Error() string {
    return fmt.Sprintf("error code %d", e.Code)
}

이제 MyError는 error 인터페이스를 만족한다. 함수가 error를 반환하는 자리에 MyError를 그대로 돌려줄 수 있다.

nil이 “에러 없음”인 이유

여기서 인터페이스의 성질 하나가 핵심으로 작동한다. nil은 모든 인터페이스 타입의 zero value다(06편에서 포인터의 zero value가 nil이었던 것과 같은 맥락이다). error도 인터페이스이므로, 아직 아무 에러도 담기지 않은 상태는 자연스럽게 nil이 된다.

그래서 Go는 “에러가 없다”를 표현하는 데 별도 장치가 필요 없다. 그냥 nil을 반환하면 된다. 호출자는 err == nil이면 성공, err != nil이면 실패로 읽는다. 이 단순한 규칙이 뒤에 나올 모든 패턴의 토대다.

Python의 None과 다른 점

Python에서 None은 “값이 없음”을 뜻하는 단일 객체일 뿐, 에러 처리와 직접 연결되지 않는다. 에러는 예외로 따로 던진다. Go의 nil은 “에러 없음”이라는 의미를 에러 처리 규약 자체에 녹여 쓴다. 함수가 error를 반환하는데 nil이면, 그건 곧 “이번엔 문제없다”는 뜻이다.

---

2. 에러 만들고 반환하기

에러 값을 만드는 가장 기본적인 방법은 두 가지다.

• errors.New("메시지") — 고정 문자열 에러를 만든다
• fmt.Errorf("형식 %v", 값) — 값을 끼워 넣어 포매팅한 에러를 만든다

import (
    "errors"
    "fmt"
)
 
func sqrt(x float64) (float64, error) {
    if x < 0 {
        return 0, errors.New("음수의 제곱근은 정의되지 않음")
    }
    if x > 1e308 {
        return 0, fmt.Errorf("입력값이 너무 큼: %v", x)
    }
    return math.Sqrt(x), nil
}

errors.New는 어떻게 동작하나

errors.New(text)는 내부적으로 text를 작은 구조체에 담고 그 포인터를 반환한다. 그 구조체가 Error() string 메서드 하나를 가져 error 인터페이스를 만족하므로(07편), err.Error()나 fmt.Println(err)은 그 메서드를 불러 담아둔 텍스트를 꺼낸다.

// 표준 라이브러리 (요약)
func New(text string) error { return &errorString{text} }
type errorString struct{ s string }
func (e *errorString) Error() string { return e.s }

포인터를 반환하므로 텍스트가 같아도 호출마다 다른 값이 된다(errors.New("x") == errors.New("x")는 false). 이 “값마다 고유함”이 3번 센티넬 오류에서 errors.Is가 정확히 그 값만 잡아내는 토대가 된다.

(결과, error) 다중 반환 관용구

05편에서 예고한 패턴이 여기서 본격적으로 등장한다. Go 함수는 여러 값을 반환할 수 있고, 그중 마지막 반환값을 error 타입으로 두는 것이 관용구다.

func divide(a, b int) (int, error) {
    if b == 0 {
        return 0, errors.New("0으로 나눌 수 없음")
    }
    return a / b, nil
}

성공하면 (결과, nil), 실패하면 (zero value, 에러)를 반환한다. 실패 시 첫 반환값을 0이나 빈 값으로 채우는 건 관례다. 어차피 호출자가 에러를 먼저 확인하고 결과는 안 쓸 것이기 때문이다.

호출하는 쪽은 반환된 에러를 곧바로 확인한다.

result, err := divide(10, 0)
if err != nil {
    fmt.Println("실패:", err)
    return
}
fmt.Println("결과:", result)

if err != nil로 시작하는 이 블록이 Go 코드 전반에 끝없이 반복된다. 처음엔 장황해 보이지만, 에러가 발생할 수 있는 모든 지점이 코드에 그대로 드러난다는 장점이 있다. 어디서 무엇이 실패할 수 있는지 숨지 않는다.

Python과 나란히 두면

같은 일을 Python은 예외로 처리한다. 던지는 쪽은 raise, 받는 쪽은 try/except다.

# Python — 예외로 처리
def divide(a, b):
    if b == 0:
        raise ValueError("0으로 나눌 수 없음")
    return a // b
 
try:
    result = divide(10, 0)
    print("결과:", result)
except ValueError as e:
    print("실패:", e)

차이를 정리하면 이렇다.

	Python	Go
에러를 알리는 법	raise로 던짐	반환값으로 돌려줌
에러를 받는 법	try/except로 감쌈	if err != nil로 확인
처리 위치	호출 흐름 어딘가(멀어도 됨)	호출 직후, 바로 그 자리
안 받으면	위로 전파되다 프로그램 종료	그냥 무시됨(컴파일은 됨)

마지막 줄이 중요하다. Python은 예외를 안 받으면 결국 프로그램이 죽지만, Go에서 에러는 그냥 값이라 무시해도 컴파일된다. 그래서 에러를 확인하는 책임이 전적으로 개발자에게 있다.

에러를 의도적으로 버릴 때

정말 에러를 무시해도 되는 자리라면 _로 명시적으로 버린다. result, _ := divide(10, 2)처럼 쓰면 “에러를 봤고 일부러 안 쓴다”는 의도가 코드에 남는다. 아무 표시 없이 흘려보내는 것과 다르다.

---

3. 센티넬 오류(sentinel error)

때로는 호출자가 에러의 종류를 구분해서 다르게 처리해야 한다. “찾는 게 없어서 실패”와 “권한이 없어서 실패”는 대응이 다르기 때문이다. 이럴 때 쓰는 게 센티넬 오류, 미리 정의해둔 대표 에러 값이다.

var ErrNotFound = errors.New("not found")
 
func lookup(id int) (string, error) {
    name, ok := db[id]
    if !ok {
        return "", ErrNotFound   // 미리 정의한 그 값을 그대로 반환
    }
    return name, nil
}

ErrNotFound는 패키지 레벨에 한 번 선언해두고 계속 재사용한다. 이름 앞에 Err을 붙이는 게 관례다(표준 라이브러리의 io.EOF, sql.ErrNoRows가 이런 식이다).

센티넬은 "타입"이 아니라 "값"이다

센티넬 오류는 새 타입을 만드는 게 아니다. errors.New로 만든 평범한 에러 값 하나를 패키지에 박아두고, 그 값 자체를 종류의 표식으로 쓰는 것뿐이다. 그래서 담기는 정보는 “이 종류가 일어났다”가 전부다. “어떤 키를 못 찾았는지” 같은 부가 데이터까지 들고 가야 한다면 값 하나로는 부족하고, 그때는 4·5번에서 다룰 커스텀 에러 타입(errors.As로 꺼내 쓰는)으로 넘어간다.

호출자는 이 값과 비교해서 “찾는 게 없는 경우”만 따로 처리한다.

name, err := lookup(42)
if errors.Is(err, ErrNotFound) {
    fmt.Println("그런 ID 없음, 기본값 사용")
    name = "guest"
} else if err != nil {
    return err   // 다른 에러는 위로 전파
}

문자열 비교는 금지

여기서 가장 중요한 규칙 하나. 에러를 메시지 문자열로 비교하면 안 된다.

// 하지 말 것 — 메시지가 조금만 바뀌어도 깨진다
if err.Error() == "not found" {
    // ...
}

메시지는 사람이 읽으라고 있는 것이지 프로그램이 분기하라고 있는 게 아니다. 오타를 고치거나 문구를 다듬는 순간 비교가 깨진다. 대신 errors.Is(err, ErrNotFound)로 값 자체를 비교한다(다음 섹션에서 errors.Is를 자세히 본다).

모든 에러를 센티넬로 만들 필요는 없다

센티넬은 호출자가 그 종류를 보고 분기해야 할 때만 만든다. 그냥 위로 전파하다 로그만 남길 에러라면 fmt.Errorf로 만든 일반 에러로 충분하다. 센티넬을 남발하면 패키지의 공개 API가 늘어나고, 호출자가 그 값에 의존하게 되어 나중에 바꾸기 어려워진다.

Python의 예외 클래스와 비교

Python에서 에러 종류를 구분하는 건 예외 클래스다. except FileNotFoundError처럼 타입으로 잡는다. Go의 센티넬은 그 자리를 값 하나로 대신하는 셈이라, “예외 클래스 없이 값으로 분기한다”가 Python 개발자에겐 낯설게 느껴질 수 있다.

---

4. 오류 래핑(wrapping)

에러가 깊은 곳에서 올라올 때, 그냥 그대로 전파하면 “어디서 무엇을 하다 났는지” 문맥이 사라진다. not found라는 메시지만 봐서는 어느 단계에서 났는지 알 수 없다. 래핑은 원본 에러를 보존한 채 문맥을 덧붙이는 방법이다.

핵심은 fmt.Errorf의 %w 동사다.

func fileChecker(name string) error {
    f, err := os.Open(name)
    if err != nil {
        return fmt.Errorf("in fileChecker: %w", err)   // %w로 원본을 감쌈
    }
    defer f.Close()
    return nil
}

%w로 감싸면 새 에러가 만들어지되, 그 안에 원본 에러가 그대로 들어 있다. 메시지는 in fileChecker: open data.txt: no such file or directory처럼 바깥 문맥과 원본이 이어진 형태가 된다. 호출 경로를 따라 여러 번 래핑하면 “어디 → 어디 → 어디서 났다”는 흐름이 한 줄에 쌓인다.

%w와 %v의 차이

fmt.Errorf에서 에러를 끼울 때 %w와 %v는 결과가 다르다.

• %v — 원본의 메시지 텍스트만 가져다 붙인다. 원본 에러 값은 버려진다.
• %w — 원본 에러 값을 체인에 보존한다. 나중에 errors.Is/errors.As로 꺼내볼 수 있다.

종류를 구분해야 할 에러라면 %w로 감싸 체인을 유지하고, 단순히 메시지만 남기면 되는 경우엔 %v를 쓴다.

errors.Unwrap — 한 겹 벗기기

래핑된 에러에서 바로 안쪽 에러를 꺼내는 함수가 errors.Unwrap이다. 한 번에 한 겹씩 벗긴다.

err := fileChecker("missing.txt")
inner := errors.Unwrap(err)   // "in fileChecker:" 를 벗기고 안쪽 에러를 꺼냄

다만 실무에서 Unwrap을 직접 호출할 일은 많지 않다. 보통은 다음 섹션의 errors.Is/errors.As가 내부에서 알아서 체인을 끝까지 풀며 검사해준다.

커스텀 에러 타입을 체인에 참여시키기

내가 만든 에러 타입도 Unwrap() error 메서드를 구현하면 래핑 체인에 낄 수 있다. 안에 감싼 에러를 돌려주도록 작성하면 된다.

type StatusError struct {
    Code int
    Err  error   // 감싼 원본 에러
}
 
func (e StatusError) Error() string {
    return fmt.Sprintf("status %d: %v", e.Code, e.Err)
}
 
func (e StatusError) Unwrap() error {
    return e.Err   // 체인의 다음 고리를 알려줌
}

이렇게 해두면 StatusError로 감싼 에러도 errors.Is/errors.As가 안쪽까지 따라 들어가 검사한다.

언제 래핑하나

에러를 위로 그냥 흘려보낼 거면 래핑 없이 그대로 return err해도 된다. 래핑은 호출 경로의 문맥이 디버깅에 도움이 될 때 한다. “어느 함수에서 이 에러를 받았는가”가 추적에 의미 있는 지점에서만 %w로 한 겹 덧붙이는 게 적당하다. 모든 단계에서 무작정 감싸면 메시지만 길어진다.

---

5. errors.Is 와 errors.As

래핑이 생기면 문제가 하나 따라온다. 에러가 여러 겹으로 감싸지면, 바깥만 봐서는 안쪽에 무엇이 있는지 모른다. 그래서 == 직접 비교나 타입 단언(type assertion)이 겉만 보고 실패한다.

err := fileChecker("missing.txt")   // os.ErrNotExist를 in fileChecker로 감쌈
 
if err == os.ErrNotExist {          // false — 바깥은 fmt가 만든 다른 값이다
    // 여기 절대 안 들어옴
}

이 문제를 풀어주는 게 errors.Is와 errors.As다. 둘 다 체인을 끝까지 따라 들어가며 검사한다.

errors.Is — “이게 바로 그 에러야?” (값 비교)

errors.Is(err, target)는 체인 어딘가에 target과 같은 값이 있는지 확인한다. 주로 센티넬 오류를 찾을 때 쓴다.

err := fileChecker("missing.txt")
 
if errors.Is(err, os.ErrNotExist) {   // 체인을 풀며 os.ErrNotExist를 찾음 → true
    fmt.Println("파일이 없습니다")
}

겉이 몇 겹으로 감싸였든, 안에 그 센티넬 값이 들어 있으면 true다. 3번에서 “문자열 비교 금지, errors.Is로 비교”라고 한 게 이것이다.

errors.As — “이런 타입 에러가 있어? 있으면 꺼내줘” (타입 확인 + 추출)

errors.As(err, &target)는 체인 안에 특정 타입의 에러가 있는지 확인하고, 있으면 그 값을 target에 꺼내 담는다. 값 하나를 콕 집어 찾는 Is와 달리, “이 부류의 에러”를 찾아 그 안의 필드까지 꺼내 쓸 때 쓴다.

var statusErr StatusError
if errors.As(err, &statusErr) {        // 체인에서 StatusError를 찾으면
    fmt.Println("상태 코드:", statusErr.Code)   // 꺼낸 값의 필드를 사용
}

As에는 받을 변수의 주소(&statusErr)를 넘긴다. 찾은 에러를 거기에 채워 넣어야 하기 때문이다. 반환값은 찾았는지 여부(bool)다.

둘을 나란히 정리하면

	무엇을 묻나	무엇을 넘기나	언제 쓰나
errors.Is(err, target)	”이 값이 체인에 있나?”	비교할 에러 값	센티넬 오류 구분
errors.As(err, &target)	”이 타입이 체인에 있나? 꺼내줘”	담을 변수의 주소	커스텀 에러의 필드 사용

comma-ok처럼 안전하다

errors.As는 03편의 맵 조회(v, ok := m[k])나 타입 단언의 comma-ok 형태와 닮았다. 찾으면 값을 채우고 true, 못 찾으면 그대로 두고 false를 준다. 패닉 없이 “있으면 쓰고, 없으면 분기”가 깔끔하게 된다. 래핑된 에러를 다룰 때는 직접 ==나 단언을 쓰지 말고 거의 항상 Is/As를 쓴다고 보면 된다.

---

6. panic과 recover

지금까지 본 에러는 전부 “값”이었다. 함수가 정상적으로 반환하고, 호출자가 처리할 수 있는 문제다. 그런데 계속 실행하는 것 자체가 위험한 상황이 따로 있다. 프로그램 상태를 더 이상 믿을 수 없는 경우다. 이럴 때 쓰는 게 panic이다.

func mustParseConfig(path string) Config {
    data, err := os.ReadFile(path)
    if err != nil {
        panic("필수 설정 파일을 읽을 수 없음: " + err.Error())
    }
    // ...
}

panic이 발생하면 보통의 에러와 다르게 동작한다.

• 현재 함수의 실행이 즉시 멈춘다
• 쌓여 있던 defer들은 그래도 실행된다(자원 정리는 보장된다)
• 그 함수를 호출한 위로 거슬러 올라가며 같은 일을 반복한다
• 끝까지 아무도 막지 못하면 프로그램이 종료되고 스택 트레이스가 출력된다

recover — defer 안에서 panic을 수습

recover는 진행 중인 panic을 멈추고 프로그램을 정상 흐름으로 되돌린다. 단, defer로 미룬 함수 안에서만 작동한다(05편의 defer와 이어진다). panic이 defer를 실행시키는 성질을 이용하는 것이다.

func safeRun() (err error) {
    defer func() {
        if r := recover(); r != nil {       // panic을 잡아냄
            err = fmt.Errorf("패닉 복구: %v", r)   // 에러로 변환해 반환
        }
    }()
 
    riskyOperation()   // 여기서 panic이 나도
    return nil         // recover가 잡아서 정상 반환으로 바꿈
}

여기서 05편의 명명된 반환값(named return value)이 함께 쓰인다. recover로 잡은 값을 err에 담으면, defer가 끝난 뒤 그 err이 최종 반환값이 된다. panic을 일반 에러로 바꿔 호출자에게 정상적으로 돌려주는 패턴이다.

기준: error냐 panic이냐

둘을 가르는 기준은 명확하다.

	error	panic
어떤 상황	호출자가 정상 처리 가능한 문제	계속 실행하면 프로그램 상태를 믿을 수 없는 문제
예시	파일 없음, 잘못된 입력, 네트워크 실패	프로그래머 버그, 불변식(invariant) 위반, 초기화 실패, 도달 불가 경로
흐름	자동 정지 없음, 반환값으로 알림	실행 강제 중단, 위로 전파
막지 않으면	그냥 무시됨	프로그램 종료 + 스택 트레이스

실무 기준은 단순하다. 호출자가 합리적으로 대응할 수 있는 문제면 error, 그렇지 않고 “여기까지 왔다는 것 자체가 버그”인 문제면 panic. 대부분의 일상적인 실패는 error로 처리하고, panic은 정말 예외적인 상황에만 남겨둔다.

Python 예외와의 결정적 차이

Python에서 예외는 일상적인 흐름 제어에도 쓰인다. 반복자가 끝나면 StopIteration을 던지고, 키가 없으면 KeyError를 던진다. try/except로 흐름을 분기하는 게 흔한 패턴이다.

Go의 panic은 그 반대다. panic은 비상용이다. “흐름 제어”로 쓰는 게 아니라, 정말 더 진행하면 안 될 때만 터뜨린다. Python의 예외에 익숙하다면 panic을 try/except처럼 쓰고 싶을 수 있지만, Go에서 그건 안티패턴이다. Python의 예외 ≈ Go의 error이고, Go의 panic은 Python에서 잡지 않고 프로그램을 죽게 두는 치명적 예외에 가깝다.

panic을 흐름 제어로 쓰지 말 것

“에러 반환이 귀찮으니 panic으로 던지고 recover로 받자”는 유혹이 있다. Go에서는 권장되지 않는다. panic/recover는 패키지 경계를 넘지 않게 가두고, 공개 함수는 가능하면 error를 반환하도록 만든다. 라이브러리 안에서 panic을 쓰더라도, 경계에서 recover로 잡아 error로 바꿔 내보내는 게 관례다.

---

7. defer로 에러 래핑하기

함수에 return 지점이 여러 개일 때, 모든 에러에 똑같은 문맥을 붙이려면 매번 fmt.Errorf를 반복해야 한다. 이걸 한 곳에서 처리하는 패턴이 있다. 명명된 반환값(named return value) 과 defer 클로저를 조합하는 것이다.

func loadUser(id int) (err error) {   // 반환 에러에 err라는 이름을 줌
    defer func() {
        if err != nil {
            err = fmt.Errorf("loadUser(%d): %w", id, err)   // 나가는 에러에 문맥을 한 번에 덧붙임
        }
    }()
 
    if err := validateID(id); err != nil {
        return err   // 여기서 나가도
    }
    if err := fetchFromDB(id); err != nil {
        return err   // 여기서 나가도
    }
    return nil       // nil이면 defer가 건드리지 않음
}

return err이 어느 지점에서 일어나든, defer 클로저가 마지막에 err을 한 번 검사해 문맥을 입힌다. loadUser(42): ... 접두사가 모든 실패 경로에 자동으로 붙는다. 05편에서 본 “defer로 명명된 반환값 수정”이 에러 처리에서 이렇게 활용된다.

과하면 가독성을 해친다

이 패턴은 return 지점이 많고 문맥이 공통일 때 유용하지만, 남용하면 에러가 어디서 어떻게 가공되는지 한눈에 안 들어온다. return이 한두 개뿐이라면 그냥 그 자리에서 fmt.Errorf("...: %w", err)로 감싸는 게 더 읽기 쉽다. defer 래핑은 “공통 문맥을 한 번에 붙일 가치가 있을 때”만 쓴다.

Python 개발자를 위한 한 줄 요약

Go에서 에러는 던지고 받는 예외가 아니라, 반환하고 확인하는 값이다. if err != nil이 반복돼도, 실패 가능한 모든 지점이 코드에 드러난다는 게 이 방식의 핵심이다. panic은 그 규칙의 예외가 아니라, 규칙이 통하지 않는 비상 상황 전용으로만 남겨둔다.