올려주신 메시지만으로는 바로 해결이 가능한 만큼의 단서는 없네요.

보통 빌드 결과물을 지정하는 경로에 문제가 있을 가능성이 큽니다.

로컬에서 빌드해보시고 어떤 디렉터리에 빌드 결과가 나오는지 확인해보세요.!

참고)

https://vercel.com/docs/errors/NOT_FOUND

💡 1. 해결 방법 제안: 핵심 점검

404 NOT_FOUND 오류는 서버가 요청을 성공적으로 수신했지만, 요청된 URL(경로)와 일치하는 라우트나 리소스를 찾을 수 없음을 의미합니다.

이를 해결하려면 클라이언트가 요청한 경로와 서버에 정의된 라우트를 면밀히 비교해야 합니다.

실행 가능한 조치 단계 (순서대로 확인하세요):

1. URL 경로 확인:

   • 클라이언트 측: 브라우저, API 호출 또는 구성 파일의 URL을 확인하세요. 대소문자 구분, 복수형 사용 여부(예: /user 대 /users), 후행 슬래시(/api/data 대 /api/data/) 등을 포함하여 경로가 정확히 일치하는지 확인하세요.

   • 예시 수정: 클라이언트가 GET /api/v1/user/42를 요청했지만, 서버 라우트가 app.get('/api/v1/users/:id', ...)로 정의되어 있다면, 클라이언트가 /api/v1/users/42를 요청하도록 수정하세요.

2. 서버 라우트 정의 확인:

   • Express(Node.js), Flask(Python), Spring Boot(Java)와 같은 프레임워크를 사용 중이라면, HTTP 메서드(GET, POST, PUT, DELETE)와 경로가 핸들러 함수에 올바르게 매핑되어 있는지 확인하세요.

   • 흔한 실수:/users/:id와 같은 동적 경로의 경우, 해당 라우트가 어떤 "캐치올(catch-all)" 또는 404 미들웨어보다 먼저 올바르게 등록되었는지 확인하세요.

3. 정적 자산 확인:

   • CSS, JavaScript, 이미지 파일 등을 가져오려고 할 때 오류가 발생했다면, 웹 서버(또는 프레임워크)가 정적 파일을 제공하도록 올바르게 설정되어 있는지, 그리고 파일이 예상되는 디렉토리에 존재하는지 확인하세요.

📝 2. 근본 원인 설명

**404 NOT_FOUND**는 서버의 정확한 통신입니다: "나는 당신의 언어(HTTP)는 이해했지만, 당신이 알려준 주소는 내가 관리하는 어떤 것과도 일치하지 않습니다."

• 코드가 실제로 한 일 vs. 해야 했던 일:

  • 실제로 한 일:클라이언트가 특정 경로(예: /v2/data)를 요청했습니다. 서버는 라우팅 로직을 실행했지만 일치하는 항목을 찾지 못하여, 기본 핸들러로 넘어갔고, 이 핸들러가 404 상태 코드를 전송했습니다.

  • 해야 했던 일: 서버의 라우팅 테이블에 /v2/data 경로에 대한 정확한 항목이 포함되어 있어야 했습니다 (또는 클라이언트에서 경로를 올바르게 구현해야 했습니다).

• 특정 오류를 유발하는 조건:

  1. 경로 누락: 요청된 경로에 대한 서버 측 라우트 핸들러가 아예 정의되지 않았습니다.

  2. 잘못된 구성: 리버스 프록시(예: Nginx, API Gateway)가 존재하지 않는 백엔드 경로로 요청을 전달하고 있거나, 라우트 정의를 포함하는 구성 파일이 배포 시 로드되지 않았습니다.

  3. 리소스 부재: 경로는 유효하지만(예: /user/42), 서버가 데이터베이스에서 사용자 ID 42를 확인했지만 존재하지 않습니다. (라우트가 유효하더라도 리소스를 찾을 수 없음을 나타내기 위해 404를 반환하는 것이 일반적인 관행입니다.)

• 간과하거나 오해한 점:

  • 경로의 엄격성: 웹 경로는 운영 체제의 파일 경로처럼 유연할 것이라고 가정하는 것. 웹 라우트는 엄격합니다./Data는 /data와 같지 않습니다.

  • 배포 불일치: 클라이언트가 여전히 이전, 이제는 삭제된 엔드포인트를 호출하도록 구성되어 있는데, 서버 변경 사항만 배포하는 것입니다.

📚 3. 핵심 개념 교육: HTTP 라우팅 및 리소스

왜 이 오류가 존재하며, 무엇으로부터 보호하는가?

404 오류는 HTTP 상태 코드의 기본 요소 중 하나입니다 (특히 4xx 범위의 클라이언트 오류 코드).

• 목적: 오류가 클라이언트 측에 있음을 서버가 클라이언트에게 표준화된 방식으로 알려줍니다.

• 보호 기능: 이는 **내부 서버 오류(5xx)**와 구별됩니다. 404는 "서버는 잘 실행되고 있지만, 이 주소는 알지 못한다"고 말하는 것입니다. 이는 "요청을 처리하려다가 충돌이 발생했다"는 **500 Internal Server Error**보다 훨씬 낫습니다.

올바른 멘탈 모델: 주소록 검색

서버를 공공 도서관이라고 생각해 보세요.

1. 클라이언트가 요청을 보냅니다: "나는 D-404번 선반, 3번 통로에 있는 책을 원합니다" (이것이 URL입니다).

2. 서버(사서)는 주소록(라우팅 테이블)을 확인합니다.

   • 시나리오 A (404): 사서가 "내 주소록에는 D-404번 선반이 없습니다. 이 주소는 여기에 존재하지 않습니다"라고 말합니다.

   • 시나리오 B (200 OK): 주소가 존재하고, 사서가 선반으로 가서 책을 찾아 건네줍니다.

광범위한 프레임워크/언어 설계에 어떻게 부합하는가?

대부분의 웹 프레임워크(Express, Flask 등)는 순서가 지정된 시스템을 구현합니다:

1. 미들웨어/핸들러: 요청은 순차적으로 함수를 통과합니다(로깅, 인증 등).

2. 라우터: 요청이 라우터에 도달하면, 라우터는 URL과 HTTP 메서드를 정의된 라우트와 일치시키려고 시도합니다.

3. 404 폴백(Fallback): 라우터가 모든 라우트를 확인했지만 일치하는 항목이 없으면, 요청은 가장 마지막 핸들러, 즉 일반적으로 프레임워크의 기본 404 핸들러로 넘어갑니다.

⚠ 4. 경고 신호 및 향후 방지책

다시 발생할 수 있는 원인으로 무엇을 찾아야 할까요?

• 경로 대소문자: 운영 체제나 프레임워크가 대소문자를 구분하는 경우, 불일치(예: api/users 대 API/USERS)를 확인하세요.

• 라우트 대 리소스: 항목 목록을 반환하는 엔드포인트(/api/items)는 작동해야 합니다. 특정 항목을 반환하는 엔드포인트(/api/items/999)는 항목 999가 존재하지 않는 경우, 목록 엔드포인트가 잘 작동하더라도 **404**를 반환할 것입니다.

관련 시나리오에서 저지를 수 있는 유사한 실수:

• 400 Bad Request와 404 Not Found 혼동: 클라이언트가 유효한 경로를 보내더라도 요청 본문 내부의 데이터가 잘못된 경우(예: 필수 필드 누락), 서버는 **400 Bad Request**로 응답해야 하며, 404가 아닙니다. 이 둘을 혼동하는 것은 일반적인 API 설계 오류입니다.

• 권한 부여되지 않은 액세스에 404 사용: 로그인했지만 리소스에 대한 접근 권한이 없는 사용자에게 404를 사용하지 마세요. 대신 **403 Forbidden**을 사용해야 합니다. 404를 사용하면 실제 문제(권한 부여)를 가릴 수 있습니다.

이 문제를 나타내는 코드 스멜(Code Smells) 또는 패턴:

• 흩어져 있는 라우트 정의: 라우트가 명확하고 중앙 집중화된 인덱스 없이 여러 파일이나 모듈에 정의되어 있다면, 그 중 하나를 로드하거나 등록하는 것을 잊기 쉽습니다.

• 상대 경로 문제: 주변 URL 구조가 변경될 때 깨지는 클라이언트 측 상대 경로(예: /admin/dashboard에서 /admin/settings로 이동할 때 깨지는 <img src="../images/logo.png">)를 사용하는 경우. 항상 절대 경로 또는 경로 헬퍼를 사용하는 것이 좋습니다.

🔄 5. 대안 및 장단점

접근 방식사용 시점장단점404 Not Found (표준)라우트가 존재하지 않음 또는 리소스가 존재하지 않음.장점: 보편적인 표준입니다. 단점: 존재하지 않는 라우트와 존재하지 않는 리소스 ID를 구별하지 않습니다.410 Gone리소스가 이전에 존재했지만 이제 영구적으로 제거됨.장점: 클라이언트(및 검색 엔진)에게 다시 시도하지 않아야 함을 명확하게 전달합니다. 단점: 서버가 모든 영구적으로 삭제된 ID를 기억해야 하므로 오버헤드가 추가됩니다.403 Forbidden리소스는 존재하지만 현재 사용자에게 볼 수 있는 권한이 없음.장점: 권한 문제를 명확하게 구분하여 디버깅이 쉽습니다. 단점: 리소스의 존재를 노출하며, 때로는 보안 위험이 될 수 있습니다.

모범 사례: 실제로 존재하지 않는 경로와 ID로 요청했지만 데이터베이스에서 찾을 수 없는 리소스 모두에 대해 **404 NOT_FOUND**를 사용하는 것이 일반적이고 가장 혼란이 적은 접근 방식입니다.

NOT_FOUND

Last updated October 6, 2025

The NOT_FOUND error occurs when a requested resource could not be found. This might happen if the resource has been moved, deleted, or if there is a typo in the URL.

404

NOT_FOUND:

Not Found

Troubleshoot

I'm encountering an error and reviewing the docs at /docs/errors/NOT_FOUND to understand what's happening. Please help me resolve this by: 1. Suggest the fix: Analyze my codebase context and propose what needs to be changed to resolve this error 2. Explain the root cause: Break down why this error occurred: - What was the code actually doing vs. what it needed to do? - What conditions triggered this specific error? - What misconception or oversight led to this? 3. Teach the concept: Help me understand the underlying principle: - Why does this error exist and what is it protecting me from? - What's the correct mental model for this concept? - How does this fit into the broader framework/language design? 4. Show warning signs: Help me recognize this pattern in the future: - What should I look out for that might cause this again? - Are there similar mistakes I might make in related scenarios? - What code smells or patterns indicate this issue? 5. Discuss alternatives: Explain if there are different valid approaches and their trade-offs My goal is to fix the immediate issue while building lasting understanding so I can avoid and resolve similar errors independently in the future.

To troubleshoot this error, follow these steps:

1. Check the deployment URL: Ensure that the deployment URL you are using is correct and does not contain any typos or incorrect paths

2. Check deployment existence: Verify that the deployment exists and has not been deleted

3. Review deployment logs: If the deployment exists, review the deployment logs to identify any issues that might have caused the deployment to be unavailable

4. Verify permissions: Ensure you have the necessary permissions to access the deployment

5. Contact support: If you've checked the above and are still unable to resolve the issue, contact support for further assistance

안녕하세요, 인프런 AI 인턴입니다. forever1542님.

Vercel에서 404 Not Found 에러를 겪고 계시군요. 이는 보통 Vercel이 설정된 라우팅 경로나 파일에 접근하지 못할 때 발생할 수 있습니다. 촬영하신 스크린샷으로 404 에러가 발생하는 부분을 보면서 몇 가지 주요 점검 사항을 안내드립니다:

1. 환경설정 파일 확인: .vercel 디렉토리나 vercel.json 파일이 제대로 설정되어 있는지 확인해보세요. 특정 경로나 페이지에 대한 설정이 누락되었거나 잘못 설정될 경우 404 에러가 발생할 수 있습니다.

2. 정적 파일 확인: 프로젝트의 빌드 아티팩트(output directory)가 잘못 설정되어 있으면 Vercel이 올바른 디렉토리를 찾지 못할 수 있습니다. 예를 들어 Next.js 프로젝트의 경우 기본적으로 .next 디렉토리가 빌드 아티팩트가 됩니다.

3. Vercel 프로젝트 설정 확인: Vercel 대시보드 설정 페이지에서 도메인 및 라우팅 설정을 재확인해보세요. 특히 맞춤 도메인 설정을 사용하고 있는 경우 경로 매핑 문제가 발생할 수 있습니다.

4. Next.js의 경우: next.config.js 파일 안에서 잘못된 Path 또는 미들웨어 설정이 문제일 수 있습니다. 특히 API 라우트의 경로나 페이지 컴포넌트의 경로가 잘못된 경우 이를 체크하세요.

5. 배포 로그 확인: Vercel의 대시보드에서 배포 로그를 확인하여 더 상세한 오류 메시지를 찾을 수 있습니다.

6. 라우트 검사: 특정 페이지가 Vercel을 통해 렌더링되지 않을 경우, “catch-all” 라우트나 API 라우트의 설정을 검토해 보시는 것도 좋은 방법입니다.

다음 문서도 도움이 될 수 있습니다:
- Vercel 공식 문서
- 환경 설정링크

이러한 방법들을 시도해 보시고 문제가 계속된다면 추가적인 정보를 통해 더 자세히 안내 드릴 수 있습니다.

저는 질문자님의 이해를 돕고자 기존 답변을 참고하여 유사한 답변 링크를 추천해드리고 있습니다.
현재 베타 기능으로 답변이 만족스럽지 않을 수 있는 점 양해 부탁드립니다. 🙏
추가적으로 궁금한 점이 있으시면, 이어서 질문해 주세요. 곧 지식공유자께서 답변해 주실 것입니다.