HTTP 개발 주소에서 브라우저 기능이 실행되지 않아요
HTTP 개발 주소에서 Service Worker·위치·카메라 같은 브라우저 기능이 실행되지 않을 때 보안 컨텍스트 오류와 Mixed Content 차단을 구분하는 가이드입니다.
AI가 만든 코드에서 오류가 발생했어요
AI 코딩 도구로 웹 애플리케이션을 만들고 배포할 때 발생하는 문제를 다룹니다. AI가 원인이라고 단정하지 않고, 실제 로그와 화면에 표시된 증상을 기준으로 확인 순서를 안내합니다.
오류 원문을 먼저 확인해 주세요
아래 문서에서 현재 화면이나 로그와 같은 표현을 찾은 뒤, 연결된 Problem의 진단 항목을 확인합니다. 원인이 확인되지 않으면 코드를 바로 수정하지 말고 실행 환경과 배포 로그를 함께 비교합니다.
- 화면·터미널·배포 로그의 오류 원문을 그대로 기록합니다.
- Guide에서 시작 상황을 고르고 Problem의 확인 순서를 따릅니다.
- 수정 후 같은 조건으로 다시 실행해 결과를 확인합니다.
시작 상황
대표 6개먼저 확인할 문제 해결 가이드
Prisma P2021·P2022 오류로 테이블·열이 없다고 나와요
Prisma P2021·P2022가 발생할 때 실행 환경, 실제 테이블·열, migration 기록과 배포 순서를 확인하는 방법을 설명합니다.
AI가 만든 로그인 기능이 새로고침하면 풀려요
로그인 직후에는 성공하지만 새로고침·외부 인증 콜백·다른 서브도메인 이동 뒤 세션이 사라질 때 쿠키 조건을 확인합니다.
AI가 만든 웹 코드가 이상하게 동작해요
AI가 작성한 코드를 붙인 뒤 화면·API·배포가 예상과 다르게 동작할 때 자주 반복되는 구현 실수를 분류하는 시작 가이드입니다.
AI가 만든 코드가 로컬에서는 되는데 배포에서 환경 변수를 못 읽어요
로컬 .env에서는 동작하지만 배포 빌드 또는 브라우저에서 환경 변수가 undefined일 때 프레임워크별 노출 범위를 확인합니다.
AI가 만든 코드를 배포하기 전에 무엇을 확인해야 하나요?
AI가 작성한 코드를 배포하기 전에 존재하지 않는 API, 비밀값 노출, 입력 검증, 비동기 오류, 서버·브라우저 경계를 확인하는 시작 가이드입니다.
오류·증상
대표 6개빌드·배포가 끝나지 않아요
빌드는 성공했지만 산출물, 경로, 환경 변수 때문에 배포가 실패하는 경우입니다.
배포된 클라이언트가 localhost API 주소를 호출함
AI가 생성한 fetch·axios 주소가 개발용 localhost로 고정되어 운영 브라우저에서 API를 호출하지 못하는지 확인합니다.
AI가 만든 클라이언트 번들에 서버 비밀값이 포함됨
API 키·토큰·데이터베이스 연결 문자열이 브라우저 번들·소스맵·네트워크 응답에 포함되었는지 확인합니다.
Invalid src prop: hostname is not configured under images in your next.config.js
Next.js `Image`의 외부 이미지 호스트가 `images.remotePatterns`에 정확히 등록되지 않았는지 확인합니다.
Missing Suspense boundary with useSearchParams
Next.js 공식 원문에 표시된 Missing Suspense boundary with useSearchParams 항목의 문구를 확인하는 문서입니다.
Dynamic server usage: Route used cookies() or headers()
Dynamic server usage: Route used cookies() or headers() 오류 원문이 표시될 때 의미와 확인 절차를 정리한 문서입니다.
NEXT_NOT_FOUND
NEXT_NOT_FOUND 오류 원문이 표시될 때 의미와 확인 절차를 정리한 문서입니다.
오류·증상
대표 6개페이지가 렌더링되지 않아요
브라우저나 서버 로그에 실행 오류와 5xx 응답이 표시되는 경우입니다.
ECONNRESET (Connection reset by peer)
Node.js의 ECONNRESET 원인을 요청 단계, 응답 중단, 재사용 소켓과 호출 코드의 연결 종료로 나눠 확인합니다.
Bad Request: This combination of host and port requires TLS
TLS가 필요한 서버 포트에 평문 HTTP 요청을 보내면 Tomcat 또는 Elasticsearch 등의 응답에서 표시될 수 있습니다. 요청 URL의 스킴, 포트와 TLS 종료 위치를 확인합니다.
Only secure origins are allowed
브라우저 기능이 보안 컨텍스트에서만 허용되어 HTTP 개발 주소에서 실행되지 않는 오류입니다. 현재 Origin과 window.isSecureContext를 확인하고 운영 환경은 HTTPS로 제공합니다.
ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH
Node.js에서 crypto.timingSafeEqual()에 길이가 다른 Buffer, TypedArray 또는 DataView 인수를 전달할 때 식별하는 오류 코드입니다.
ERR_INVALID_URL
Node.js가 WHATWG URL 생성자 또는 legacy url.parse()에서 유효하지 않은 URL을 파싱할 때 발생하는 오류 코드입니다.
ERR_MODULE_NOT_FOUND
Node.js에서 ECMAScript 모듈 로더가 import 작업 또는 프로그램 진입점 로드 중 모듈 파일을 해석하지 못했음을 나타내는 오류 코드입니다.
오류·증상
대표 5개로그인·인증 요청이 실패해요
세션, 토큰, 인증서 또는 권한 설정을 확인해야 하는 경우입니다.
401 {"message":"Unauthorized"}
Amazon Web Services 공식 원문에 표시된 401 {"message":"Unauthorized"} 항목의 문구를 확인하는 문서입니다.
413 (Request Entity Too Large)
nginx.org 공식 원문에 표시된 413 (Request Entity Too Large) 항목의 문구를 확인하는 문서입니다.
AuthSessionMissingError: Auth session missing!
Supabase 공식 원문에 표시된 AuthSessionMissingError: Auth session missing! 항목의 문구를 확인하는 문서입니다.
Cross-Origin Request Blocked
Amazon Web Services 공식 원문에 표시된 Cross-Origin Request Blocked 항목의 문구를 확인하는 문서입니다.
ERR_NETWORK
axios 유지보수자 저장소 공식 원문에 표시된 ERR_NETWORK 항목의 문구를 확인하는 문서입니다.
오류·증상
대표 6개데이터베이스·API 요청이 실패해요
데이터베이스 연결, 스키마, 요청 형식 때문에 기능이 완료되지 않는 경우입니다.
The column {column} does not exist in the current database.
Prisma P2022 오류를 식별하고 실행 환경의 데이터베이스, 실제 열, migration 적용 상태를 확인하는 방법을 설명합니다.
The table {table} does not exist in the current database.
Prisma P2021 오류를 식별하고 실행 환경의 데이터베이스, 실제 테이블, migration 적용 상태를 확인하는 방법을 설명합니다.
Authentication failed against database server at {database_host}, the provided database credentials for {database_user} are not valid. Please make sure to provide valid database credentials for the database server at {database_host}.
Prisma P1000 오류 메시지를 대조하여 제공된 데이터베이스 자격 증명이 유효하지 않은 경우를 식별합니다.
new row violates row-level security policy
Supabase Storage 업로드에서 403과 new row violates row-level security policy가 함께 표시되는지 확인하고 저장소 객체의 RLS 범위를 식별합니다.
ERR_SERVER_ALREADY_LISTEN
이미 수신 중인 net.Server에 server.listen()을 호출했을 때 표시되는 Node.js 오류 코드입니다.
ERR_TLS_PROTOCOL_VERSION_CONFLICT
Node.js 공식 원문에 표시된 ERR_TLS_PROTOCOL_VERSION_CONFLICT 항목의 문구를 확인하는 문서입니다.
오류·증상
대표 6개브라우저에 JavaScript 오류가 보여요
모듈, URL, 날짜, 정규식 같은 실행 오류가 브라우저나 빌드 로그에 표시되는 경우입니다.
import.meta.env.VITE_* is undefined
Vite 애플리케이션에서 import.meta.env의 환경 변수가 undefined로 보일 때 변수 이름·모드·빌드 시점을 확인합니다.
Next.js encountered the unstable value Math.random() while prerendering
prerendering 중 Server Component가 <Suspense> 밖에서 Math.random()을 호출하면 발생하는 Next.js 오류입니다.
Next.js encountered uncached data in generateMetadata()
Cache Components가 활성화된 Next.js에서 generateMetadata()가 캐시되지 않은 데이터를 읽어 메타데이터가 프리렌더링을 막는 오류입니다.
No Duplicate Head
pages/_document.js의 하나의 custom document에서 <Head />가 둘 이상 사용된 상태입니다.
The module you're trying to import has a different casing
파일명과 import 경로의 대소문자가 다르면 대소문자를 구분하는 환경에서 빌드가 실패할 수 있습니다.
CustomerError: Can't find required-server-files.json in build output directory
Next.js 빌드는 성공했지만 AWS Amplify가 배포 산출물에서 서버 실행 메타데이터 파일을 찾지 못해 배포가 중단된 상태입니다.
환경과 기술
관련 8개문제가 발생한 환경 확인
사용한 플랫폼과 기술의 조건을 함께 확인하면 원인 범위를 좁힐 수 있습니다.
Node.js
JavaScript를 브라우저 밖의 서버와 도구 환경에서 실행하는 런타임입니다.
환경 변수
실행 환경에서 애플리케이션 설정과 비밀값을 이름과 값으로 전달하는 입력입니다.
AWS Amplify Hosting
Git 저장소의 변경을 기준으로 웹 애플리케이션을 빌드하고 정적 또는 서버 실행 방식으로 배포하는 AWS 서비스입니다.
Docker
애플리케이션과 실행 환경을 이미지와 컨테이너로 패키징하고 실행하는 도구입니다.
Firebase
웹·모바일 애플리케이션에 인증, 데이터베이스, 저장소와 호스팅 기능을 제공하는 Google 플랫폼입니다.
GitHub Actions
GitHub 저장소의 이벤트를 기준으로 빌드, 테스트와 배포 작업을 실행하는 자동화 플랫폼입니다.
JavaScript 오류
브라우저 또는 JavaScript 실행 환경이 구문·참조·형 변환·실행 문제를 표시하는 오류 메시지입니다.
Next.js 빌드 산출물
Next.js가 빌드 과정에서 생성하는 정적 파일과 서버 실행용 메타데이터를 배포 방식에 맞게 구분한 결과물입니다.