2026년 Server Action undefined 오류 막는 법: stale client bundle 사용자 경험 개선

2026년 Server Action undefined 오류 막는 법: stale client bundle 사용자 경험 개선

갑자기 Server Action을 호출했는데 결과가 undefined로 떨어지는 황당한 경험을 했다. 이게 뭐지 싶어서 콘솔을 봤는데, 예상치 못한 오류 메시지가 떡하니 떠 있었다. 사용자에게는 아무것도 안 보이는데, 개발자 모드에서는 난리가 나고 있었던 거다.

시도와 함정

처음에는 단순한 API 호출 문제인 줄 알았다. 혹시나 해서 try...catch로 감싸봤는데, 에러가 잡히질 않았다. undefined가 던져지는 건 오류가 아니라고 판단하는 건가 싶어서 if (result === undefined)로 분기 처리를 해봤는데, 이것도 뭔가 찜찜했다.

// 처음 시도했던 코드 (가정)
async function handleSubmit(formData) {
  try {
    const result = await someServerAction(formData);
    if (result === undefined) {
      console.error("Server Action returned undefined!");
      // 여기서 뭘 해야 할지 막막했다.
    }
    // ... 결과 처리 ...
  } catch (error) {
    console.error("An unexpected error occurred:", error);
    // 이 catch 블록은 사실상 작동하지 않았다.
  }
}

분명히 undefined가 반환되는데, try...catch로는 잡히지 않는 상황이었다. 이게 대체 왜 이러는 건지 3시간은 삽질한 것 같다.

원인

알고 보니 문제는 stale client bundle이었다. 서버에 배포된 코드와 클라이언트에서 실행되는 코드가 일치하지 않아서 생긴 문제였다. Server Action이 실행될 때, 클라이언트 번들에는 해당 액션의 최신 버전이 로드되지 않았고, 그 결과 undefined가 반환되는 상황이 발생했던 거다. 이게 오류로 잡히지 않고 그냥 undefined로 넘어오는 게 더 문제였다.

해결

결국 stale client bundle 상황을 명확히 인지하고, Server Action의 결과가 undefined일 경우를 명시적으로 처리하도록 코드를 수정했다. 단순히 undefined를 반환하는 것을 넘어, 사용자에게 현재 상황을 친절하게 안내하는 메시지를 보여주도록 했다.

// 실제 동작한 코드
import { useRouter } from 'next/navigation';
export default function MyForm() {
const router = useRouter();
const handleSubmit = async (formData) => {
const result = await processFormData(formData); // 실제 Server Action 함수
if (result === undefined) {
  // stale client bundle 또는 예상치 못한 서버 오류 가능성
  alert("데이터 처리 중 문제가 발생했습니다. 페이지를 새로고침하여 다시 시도해주세요.");
  // 필요하다면 router.refresh() 등을 호출하여 강제로 새로고침 유도
  return;
}

// 결과가 undefined가 아닐 경우 정상 처리
router.push('/success');

};
return (
<form action={handleSubmit}>
{/* 폼 요소들 */}
<button type="submit">제출</button>
</form>
);
}
// 예시 Server Action 함수 (실제로는 서버 파일에 있어야 함)
async function processFormData(formData) {
// ... 실제 로직 ...
// 만약 stale client bundle 상황이라면 undefined를 반환할 수 있다.
// 또는 서버 자체의 오류로 인해 undefined를 반환할 수도 있다.
return undefined; // 예시를 위해 undefined 반환
}

이렇게 undefined 값을 명확하게 체크하고, 사용자에게 상황을 설명하는 알림을 띄우는 것으로 해결했다. stale client bundle이라는 특정 상황 때문에 발생한 문제였고, 이 경우 try...catch로는 잡히지 않는다는 점을 기억해야 했다.

결과

• undefined 반환으로 인한 사용자 혼란 방지.
• stale client bundle 시 친절한 안내 메시지 제공.
• 예상치 못한 오류 발생 시 디버깅 용이성 향상.

정리 — 같은 함정 안 빠지려면

• [ ] Server Action 결과가 undefined일 경우를 항상 염두에 둘 것.
• [ ] stale client bundle 가능성을 고려하여 클라이언트와 서버 코드의 일관성을 유지할 것.
• [ ] undefined 반환 시 사용자에게 명확한 피드백을 제공하는 로직을 추가할 것.
• [ ] try...catch가 모든 오류를 잡지는 못한다는 점을 인지할 것.