---
title: 설치 오류
description: NexCMP 설치 프로그램이 출력할 수 있는 모든 오류 메시지의 원인과 해결 방법(시스템 요구사항, 라이선스 활성화, 다운로드 확인, 서비스 및 nginx/TLS)을 안내합니다.
url: https://nexcmp.com/ko/docs/troubleshooting/installation-errors/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 설치 오류 {#installation-errors}

설치 프로그램은 치명적인 문제가 발생하면 즉시 중단되며 `✗`(으)로 시작하는 빨간색 줄을 출력합니다. 원인을 해결하고 **동일한 명령을 다시 실행**하세요. 설치 프로그램은 반복해서 실행해도 안전합니다. 정보성 줄은 `•`(으)로, 성공적인 단계는 `✓`(으)로 시작합니다.

## 시스템 검사 {#machine-checks}

| 메시지 | 원인 | 해결 방법 |
|---|---|---|
| `must be run as root (sudo)` | root 권한으로 실행되지 않음 | 명령어 앞에 `sudo`을(를) 붙이거나 root로 실행하세요. |
| `only Ubuntu 22.04/24.04 is supported (this host: …)` | 다른 배포판 또는 버전 | Ubuntu 22.04 또는 24.04 서버를 사용하세요. |
| `only x86_64 is supported` | ARM 또는 기타 CPU | x86_64 서버를 사용하세요. |
| `requires ≥ 2 GB RAM (host has … MB)` | 메모리 부족 | RAM을 추가하세요. |
| `requires ≥ 8 GB free disk space on / (… GB available)` | 루트 파일 시스템 용량 거의 부족 | 공간을 확보하거나 `/`을(를) 확장하세요. |
| `missing --license` / `missing --domain` | 해당 매개변수 없이 최초 설치 진행 | 둘 다 전달하세요 — [Installation](https://nexcmp.com/ko/docs/getting-started/installation/#parameters) 참고. |
| `unknown argument: …` | 매개변수 오타 | 철자를 확인하고 `--help`(으)로 실행하세요. |
| `apt-get failed (another apt/dpkg process, e.g. unattended-upgrades, may still be running)` | 패키지 매니저가 잠겨 있음 | 몇 분 정도 기다린 후(새로 설치된 Ubuntu는 부팅 후 자동 업데이트를 실행합니다) 다시 실행합니다. |
| `… is a symlink — aborting` | `/opt/nexcmp` 또는 `/etc/nexcmp`이(가) 심볼릭 링크입니다. | 보안상 설치 프로그램에서 심볼릭 링크를 허용하지 않으므로 실제 디렉터리로 교체합니다. |

## 라이선스 활성화 {#license-activation}

| 메시지 | 원인 | 해결 방법 |
|---|---|---|
| `cannot connect to https://nexcmp.com` | 라이선스 서버로 향하는 아웃바운드 HTTPS가 차단됨 | 서버의 DNS, 방화벽 및 프록시를 확인하세요: `curl -I https://nexcmp.com`. |
| `license activation failed (HTTP …): <message>` | 라이선스 서버가 키를 거부함 | 메시지를 확인하세요: 잘못된 키, 라이선스와 일치하지 않는 도메인, 정지 또는 취소된 라이선스. [nexcmp.com/licenses](https://nexcmp.com/licenses)에서 라이선스 페이지를 확인하세요. |
| `no release available for this license yet` | 라이선스에 다운로드 가능한 릴리스가 없음 | 영업팀에 문의하세요. [Support](https://nexcmp.com/ko/docs/troubleshooting/support/)을 참조하세요. |

## 다운로드 및 검증 {#download-and-verification}

| 메시지 | 원인 | 해결 방법 |
|---|---|---|
| `failed to download release X` | 다운로드 중 네트워크 문제 발생 | 다시 실행합니다. |
| `sha256 mismatch (… ≠ …)` | 파일이 손상되었거나 변조된 상태로 도착함 | 다시 실행하세요. 문제가 지속되면 프록시가 다운로드를 변조하고 있는 것일 수 있으므로 다른 네트워크에서 시도해 보세요. |
| `release X is unsigned — refusing to install` | 서버가 서명을 제공하지 않음 | 절대 우회하지 말고 지원팀에 문의하세요. |
| `INVALID SIGNATURE for version X — aborting` | Ed25519 서명 검증 실패 | 설치하지 **마세요**. 공식 릴리스 파일이 아님을 의미하므로 지원팀에 문의하세요. |
| `openssl failed to read public key` | 매우 오래되었거나 손상된 OpenSSL | `openssl` 패키지를 업데이트합니다. |
| `invalid version: …` | 서버에서 예기치 않은 데이터가 수신됨 | 다시 실행하고, 문제가 지속되면 지원팀에 문의하세요. |

## 서비스 시작 {#service-start}

| 메시지 | 원인 | 해결 방법 |
|---|---|---|
| `service failed to start — check: journalctl -u nexcmp -n 50` | 패널이 3분 이내에 `/healthz`에 응답하지 않음 | 저널을 확인하세요. 일반적인 원인: 포트(기본값 3000)가 이미 사용 중임(`ss -ltnp | grep 3000`) — `--port`을(를) 사용하여 다시 설치; `/var/lib/nexcmp` 내 파일의 소유권이 root로 되어 있음 — `sudo nexcmp fix-owner` 실행. |

## nginx 및 TLS {#nginx-and-tls}

| 메시지 | 원인 | 해결 방법 |
|---|---|---|
| `DNS <domain> does not point to <IP> (nor to Cloudflare) — skipping nginx/TLS` | A/AAAA 레코드가 누락되었거나 잘못됨 | [DNS and Cloudflare](https://nexcmp.com/ko/docs/getting-started/dns-and-cloudflare/)을(를) 참조한 후 다시 실행합니다. |
| `certbot could not get a certificate yet — re-run the installer once DNS has settled` | Let's Encrypt 검증 실패 (포트 80 차단, DNS 전파 지연, 속도 제한) | 포트 80을 열고, DNS 전파를 기다린 후 다시 실행합니다. `/var/log/letsencrypt/letsencrypt.log`을(를) 확인하세요. |
| `certbot could not renew now — keeping the existing certificate` | 일시적인 갱신 실패 | 무해하므로 나중에 다시 실행합니다. |
| `nginx rejected the HTTPS configuration — kept the previous one (check: nginx -t)` | 다른 nginx 사이트와 충돌 발생(동일한 `server_name`, 중복 설정) | `sudo nginx -t`을(를) 실행하여 충돌을 해결한 후 다시 실행합니다. |
| `apt-get could not install nginx` / `certbot` 또는 `E: Failed to fetch … 404 Not Found` | 패키지 매니저가 잠겨 있거나 서버의 패키지 색인이 오래되었습니다(업데이트한 지 오래된 템플릿 이미지에서 주로 발생함). | `sudo apt-get update`을(를) 실행하고 다른 apt 프로세스가 완료될 때까지 기다린 후 설치 프로그램을 다시 실행합니다. |
| `openssl could not create the self-signed certificate` | OpenSSL 문제 | `openssl`을(를) 업데이트한 후 다시 실행합니다. |

## 설치 후 {#after-installation}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 브라우저에서 `https://<domain>`을(를) 열 수 없음 | DNS 또는 TLS가 준비되지 않음 | `sudo nexcmp status`; [emergency access](https://nexcmp.com/ko/docs/getting-started/cli-reference/#emergency-access)을(를) 사용하세요. |
| `ERR_TOO_MANY_REDIRECTS` | Cloudflare SSL 모드가 **Flexible**으로 설정됨 | **Full (strict)**으로 설정 — [상세 정보](https://nexcmp.com/ko/docs/getting-started/dns-and-cloudflare/). |
| 마법사가 "setup code"가 잘못되었다고 표시함 | 오타 또는 이전 설치 시 발급된 코드 | `sudo nexcmp status`을(를) 실행하고 현재 코드를 복사합니다. |
| 라이선스에 HTTP 421 오류 발생 | `/var/lib/nexcmp` 안의 파일 소유권이 root로 설정됨 | `sudo nexcmp fix-owner`, 그 다음 `sudo systemctl restart nexcmp`. |