문제 해결
배포가 실패하거나 실행 중인 앱이 제대로 작동하지 않는다면 이 페이지를 순서대로 확인하세요. 사용자와 코딩 AI가 함께 볼 수 있도록 작성했습니다. AI가 배포를 담당한다면 이 페이지의 URL을 전달하세요. 대부분의 문제를 스스로 진단할 수 있습니다.
빌드 상태
모든 배포는 다음 상태를 거치는 하나의 빌드입니다.
문제가 발생하면 상태가 error로 바뀌고 원인을 설명하는 메시지가 표시됩니다. 프로젝트 페이지의 Deployments에서 상태를 확인하세요. AI가 MCP 또는 API로 연결되어 있다면 get_build로 빌드 상태를 직접 확인할 수 있습니다.
빌드 실패
- “다른 빌드가 이미 진행 중입니다” (409): 프로젝트마다 한 번에 하나의 빌드만 실행됩니다. 현재 빌드가
ready또는error상태가 될 때까지 기다린 뒤 새 빌드를 시작하세요. 자동으로 대기열에 들어가지 않으므로 완료 후 다시 시도해야 합니다. - “인증 정보가 만료되었습니다” (410): 프로젝트 페이지에서 복사하는 가이드에는 최대 24시간 동안 유효한 배포 키가 포함됩니다. 이전에 저장한 가이드는 더 이상 작동하지 않을 수 있습니다. 프로젝트를 열고 Copy를 다시 누른 뒤 새 가이드를 AI에 붙여 넣으세요. 이것만으로 충분합니다. 이 제한은 배포에만 영향을 줍니다. 배포가 성공하면 실행 중인 앱에는 영구 키가 자동으로 발급됩니다.
- 빌드가 오류로 종료됨: 먼저 빌드 오류를 확인하세요. 대개 실패 원인이 정확히 표시됩니다. 흔한 원인은 런타임 감지에 필요한
package.json이 zip에 없거나node_modules/또는 빌드 결과물이 포함된 경우입니다.package.json과 lock 파일은 포함하고node_modules/,.next/,.git/는 제외하세요. - 배포 성공 후 롤백됨: JustDeploy는 Web 및 API 프로젝트를 배포한 직후 헬스 체크합니다. 앱은 로그인이나 데이터베이스 없이
GET /요청에 정상적인 non-5xx 응답을 반환하고 플랫폼이 지정한PORT=8080에서 실행되어야 합니다.localhost나127.0.0.1에만 바인딩하면 안 됩니다. 헬스 체크에 실패하거나 프로세스가 중단되면 마지막으로 동작한 버전을 자동으로 복구합니다. Scheduler 프로젝트는 헬스 체크하지 않습니다. 아래의 스케줄러 문제를 확인하세요.
앱이 실행 중이지만 작동하지 않는 경우
- 먼저 배포 경고 확인: 프로젝트의 Deployments(배포 기록)를 여세요. 헬스 체크는 응답이 오는지만 확인하므로 상태가
Ready여도 실제 페이지가 동작하지 않을 수 있습니다. 이 경우 주황색 Deployed, but it may not be working yet(배포되었지만 아직 작동하지 않을 수 있음) 메모에 모든 경로가 404를 반환한다는 식의 검사 결과가 표시됩니다. 보통 등록된 라우트가 없거나 앱이 현재 호스트를 거부할 때 발생합니다. 불완전하거나 삭제·만료됐거나 다른 프로젝트에서 발급된 JustDeploy 키처럼 빌드 중 발견한 문제도 이 메모에 표시됩니다. 배포는 성공해도 앱이 데이터베이스나 파일에 접근하지 못할 수 있습니다. AI에는 같은 내용이 빌드의warning필드로 전달됩니다. - 로그 먼저 확인: 프로젝트 → Advanced → Logs를 열고 시간 범위를 선택한 뒤 오류로 필터링하세요. AI도
get_logsMCP 도구 또는 Logs API로 같은 로그를 가져올 수 있습니다. 같은instance값을 가진 로그 줄은 동일한 실행 컨테이너에서 나온 것이므로 하나의 충돌을 추적할 때 유용합니다. - 설정 또는 API 키 누락: 콘솔에서 Project → Advanced → Environment variables를 열어 환경 변수를 관리합니다. 값은 빌드할 때 복사되므로 저장만 해서는 실행 중인 앱에 반영되지 않습니다. Deployments(배포 기록)에서 현재 서비스 중인 버전의 Rebuild(재빌드)를 선택하거나 AI에 프로젝트를 재빌드해 달라고 요청하세요. 웹 페이지에서 사용하는 값을 포함한 모든 환경 변수에 같은 규칙이 적용됩니다.
- 일부 방문자 차단: 프로젝트에 방화벽 규칙이 있으면 일치하지 않는 IP의 모든 요청이 거부됩니다. 차단된 시도는 로그에 기록됩니다. 다음 값으로 필터링하세요.
[JUSTDEPLOY_FIREWALL]. 규칙 변경이 적용되기까지 1~2분이 걸립니다. 모든 규칙을 삭제하면 모든 트래픽이 차단됩니다. 모두 허용하려면0.0.0.0/0규칙을 추가하세요. - 로그인이 유지되지 않거나 다른 사람의 페이지가 보임: 로그인한 사람마다 달라지는 페이지를 공용 캐시에 저장하면 한 사람의 화면이 다른 방문자에게 보일 수 있습니다. 보는 사람에 따라 내용이 달라지는 페이지는 반드시
Cache-Control: private와 함께 전송해야 합니다. AI에 해당 페이지가 보내는 헤더를 확인해 달라고 요청하세요. JustDeploy도 최악의 상황을 자체 방지합니다. 쿠키를 설정하는 응답은 자동으로 private 처리되어 로그인 응답이 공유되지 않습니다. 이 보호 기능 이전에 배포한 앱은 다음 빌드부터 적용됩니다. - 실시간 기능이 연결되지 않음: WebSocket은 지원하지 않습니다. 요청마다 응답을 반환하고 연결을 종료하므로 연결을 계속 열어 둘 수 없습니다. Web 프로젝트에서는 연결이 바로 거부되고, API 프로젝트에서는 연결된 것처럼 보여도 메시지가 오지 않을 수 있습니다. socket.io가 HTTP polling으로 전환되어 잠시 작동하더라도 다음 요청이 다른 인스턴스로 가면 세션이 끊길 수 있어 신뢰할 수 없습니다. 채팅, 실시간 업데이트, 접속 상태 기능에는 전용 실시간 서비스를 사용하고, 앱은 요청 사이의 상태를 서버 메모리에 저장하지 않는 stateless 구조로 만드세요.
- 작동하던 버전으로 되돌리기: 프로젝트의 Deployments(배포 기록)를 열고 정상적으로 동작했던 이전 버전에서 Redeploy(이전 버전 다시 배포)를 선택하세요. AI도 이 작업을 할 수 있습니다. 해당 소스를 다시 빌드하므로 몇 분이 걸리며, 새 버전이 준비될 때까지 현재 버전이 계속 제공됩니다. 환경 변수는 이전 설정으로 돌아가지 않고 현재 값을 유지합니다. Redeploy는 최근 성공한 배포 10개에서만 사용할 수 있습니다.
스케줄러 문제
Scheduler 프로젝트가 실행되지 않는다면 먼저 프로젝트 페이지에서 스케줄이 Active(활성) 상태인지 확인하세요. Run now(지금 실행)를 누르면 즉시 테스트할 수 있습니다. 실행 결과는 버튼을 누른 화면에 바로 나타나지 않으므로 Logs(로그)에서 확인하세요.
Web 및 API 프로젝트와 달리 Scheduler는 배포 후 자동으로 실행해 볼 안전한 요청이 없으므로 헬스 체크와 자동 rollback을 하지 않습니다. 문제가 있는 버전도 새 버전으로 교체할 때까지 유지됩니다. 배포한 뒤 Run now(지금 실행)를 누르고 Logs(로그)에서 새 버전이 정상적으로 실행됐는지 확인하세요.
Scheduler 배포는 헬스 체크하지 않지만 경고가 표시될 수 있습니다. JustDeploy는 빌드 중 코드를 읽고 유효하지 않은 키나 /tmp 외부에 파일을 쓰려는 시도처럼 작업 실행을 방해할 문제를 찾습니다. 실행 중인 앱은 이 디렉터리 안에만 파일을 쓸 수 있습니다. 배포할 때마다 Deployments의 주황색 메모를 확인하세요. AI에는 같은 내용이 빌드의 warning 필드로 전달됩니다.
MCP 연결 문제
연결 상태를 확인하려면 AI에 list_organizations를 실행해 달라고 요청하세요. 조직 목록이 반환되면 정상적으로 연결된 것입니다. 로그인 페이지가 계속 열리거나 클라이언트에 도구가 표시되지 않는다면 MCP 문서에서 도구별 원격 MCP 설정과 “Authorization successful”이 항상 연결 완료를 뜻하지 않는 이유를 확인하세요.
커스텀 도메인이 대기 상태인 경우
DNS 레코드가 JustDeploy에 표시된 값과 다르거나 조직의 유료 플랜이 끝나면 도메인이 계속 대기 상태로 남을 수 있습니다. 먼저 Custom Domain(커스텀 도메인) 카드의 안내를 확인하세요. 유료 플랜이 필요하다고 나오면 Owner 또는 Admin이 플랜을 선택해야 합니다. 그 외에는 DNS 이름과 값을 다시 정확히 복사하세요. 변경 사항이 인터넷 전체에 반영되기까지 DNS 업체에 따라 최대 24~48시간이 걸릴 수 있습니다. 도메인은 콘솔에서만 관리할 수 있으며 AI가 대신 연결할 수는 없습니다.