2026-10-12 · 문제 해결 · 약 10분

Xray 코어 시작 실패 해결: 포트 충돌·JSON 형식·필드 오류 점검

코어가 시작 직후 종료된다면 포트 충돌, 설정 파일 형식, 필드 표기, 코어 버전을 차례로 점검해 오류가 난 위치를 찾으세요.

이 글의 핵심

v2rayN에서 Xray 시작 실패 메시지가 표시되거나, 시작 직후 종료되거나, 사용자 설정을 불러오지 못하는 경우에 적용할 수 있습니다. 먼저 오류 로그 전체를 보관하고, 수신 대기 포트와 실제 사용 중인 코어로 설정을 검사한 뒤 필드와 버전을 확인하세요. Windows 포트 확인 명령과 최소 로컬 설정을 사용해 클라이언트 생성 문제, 설정 문제, 시스템 환경 문제를 구분합니다.

1. 시작 실패인지 연결 실패인지 먼저 확인

“웹페이지가 열리지 않는다”는 것만으로 “코어가 시작되지 않았다”고 볼 수는 없습니다. Xray는 시작할 때 설정을 읽고 인바운드와 아웃바운드를 구성한 다음 수신 대기 포트를 엽니다. 이 과정에서 실패하면 프로세스가 바로 종료될 수 있습니다. 코어가 실행된 뒤 발생하는 원격 연결 시간 초과, 인증 실패, TLS 핸드셰이크 오류는 별도로 점검해야 합니다. 먼저 어느 단계에서 문제가 생겼는지 구분해야 정상적인 노드 설정을 불필요하게 바꾸지 않습니다.

v2rayN은 클라이언트 인터페이스이고 Xray는 실제 연결을 처리하는 코어입니다. 인터페이스가 계속 실행 중이어도 코어가 정상이라는 뜻은 아닙니다. 버전에 따라 메뉴 위치가 달라질 수 있으므로, 아래 설명은 Windows 데스크톱의 일반적인 화면을 기준으로 합니다. 같은 이름의 메뉴가 보이지 않으면 괄호 안의 기능을 기준으로 찾고, 다른 클라이언트의 메뉴를 그대로 적용하지 마세요.

  1. 오류 기록하기

    메인 창 아래의 정보 또는 로그 영역을 펼친 뒤 이번 시작 시각을 기록하세요. Failed to start부터 시작하는 오류 메시지 전체를 복사하고, 뒤에 이어지는 > 구분 내용도 남겨 두세요. 보통 마지막 단계의 메시지가 처음 요약보다 구체적입니다.

  2. 코어 확인

    「설정」→「매개변수 설정」→「Core 유형」에서 현재 노드 프로토콜에 맞는 코어가 선택되어 있는지 확인하세요. 일부 버전에서는 「Core 유형 설정」 탭으로 표시됩니다. 시작 로그에 나온 실행 파일 경로도 확인해 실제로 Xray가 호출되는지 점검하세요.

  3. 한 번만 재현하기

    TUN을 잠시 끄고 v2rayN 인스턴스 하나만 남긴 다음, 원래 노드를 선택해 서비스를 한 번 재시작하세요. 노드를 연속으로 바꾸며 로그를 쌓지 말고, 재시작 전후 약 10초간의 로그를 함께 보관해 오류가 같은 시작 과정에서 발생했는지 확인하세요.

  4. 변경 사항 기록

    마지막으로 정상 시작된 뒤 변경한 항목을 적어 두세요. 예를 들면 로컬 포트, 라우팅 규칙, 사용자 설정, 코어 파일 등이 있습니다. 현재 설정을 백업하고, 매번 변수 하나만 바꾼 뒤 결과를 기록하세요.

2. 포트 충돌: 수신 대기 프로세스를 확인한 뒤 포트 변경

오류에 failed to listen 또는 address already in use가 있다면 원격 노드의 443 포트가 아니라 로컬 수신 대기 포트를 먼저 확인하세요. Windows에서는 Only one usage of each socket address라는 영문 시스템 메시지가 표시될 수도 있습니다. 이전 코어가 종료되지 않았거나, 클라이언트를 여러 번 실행했거나, 다른 프로그램이 같은 주소와 포트를 사용 중일 때 흔히 발생합니다.

아래에서는 TCP 포트 10808을 예로 들어 조회합니다. 모든 v2rayN 버전의 기본값이 이 포트라는 뜻은 아닙니다. 먼저 「설정」→「매개변수 설정」→「기본 설정」에서 실제 로컬 수신 대기 포트를 확인한 다음, 명령의 숫자를 해당 값으로 바꾸세요. 혼합 인바운드를 사용하면 하나의 포트에서 여러 프록시 프로토콜을 받을 수 있으므로 포트를 억지로 둘로 나눌 필요가 없습니다.

netstat -ano -p tcp | findstr ":10808"

powershell -NoProfile -Command "Get-NetTCPConnection -State Listen -LocalPort 10808 | Select-Object LocalAddress,LocalPort,OwningProcess"

오류: bind: address already in use

원인 및 해결 방법: 지정한 수신 대기 주소와 포트가 이미 사용 중입니다. 오류에 표시된 실제 포트의 PID를 조회한 뒤 점유 중인 프로그램을 정상 종료하거나 현재 인바운드 포트를 바꾸고 다시 시작하세요.

오류: bind: permission denied

원인 및 해결 방법: 시스템에서 바인딩을 거부한 것이며, 다른 프로세스가 수신 대기 중이라는 뜻은 아닙니다. 수신 대기 주소와 포트 권한, 보안 프로그램의 차단 여부를 확인하세요. Windows에서 접근 권한 관련 메시지가 표시되면 시스템의 제외 포트 범위도 확인하고, 프로세스만 반복해서 종료하지 마세요.

Windows에서 수신 대기 프로세스가 조회되지 않는데도 소켓 접근 거부 메시지가 표시되면 netsh interface ipv4 show excludedportrange protocol=tcp을 실행해 IPv4 TCP 제외 범위를 확인하세요. 포트가 범위에 포함되어 있다면 시스템 예약 항목을 삭제하지 말고 범위 밖의 사용 가능한 포트를 선택하세요. 로그가 TUN이나 권한 문제를 가리킬 때만 해당 권한 설정을 확인하세요.

3. JSON 형식: 실제 코어로 오프라인 검사

텍스트 편집기에서 설정 파일이 열리더라도 Xray가 읽을 수 있다는 뜻은 아닙니다. 쉼표 누락, 한글 따옴표 사용, 괄호 미닫힘은 모두 파싱을 중단시킬 수 있습니다. 문법 오류에는 행 번호나 문자 위치, invalid character, unexpected EOF 같은 메시지가 표시되는 경우가 많습니다. 구체적인 문구는 코어 버전과 로드 방식에 따라 다릅니다.

클라이언트에서 관련 서비스를 중지한 뒤 로그에 표시된 Xray 프로그램 폴더로 이동하세요. 해당 폴더의 실행 파일로 저장해 둔 설정 사본을 검사합니다. 아래는 Windows PowerShell 예시이며, check.json은 검사할 파일 이름입니다. 검사 과정에서 프록시 수신 대기는 시작하지 않지만, 설정에서 참조하는 인증서나 규칙 데이터 같은 로컬 파일은 읽을 수 있습니다.

.\xray.exe version
.\xray.exe run -test -config .\check.json
오류 단서우선 확인할 항목해결 방법
invalid character오류 위치와 바로 앞 행영문 큰따옴표로 바꾸고, 키와 값 사이의 콜론 및 항목 사이의 쉼표를 확인하세요.
unexpected EOF파일 끝과 복사 범위파일이 잘리지 않았는지 확인하고, 객체의 중괄호와 배열의 대괄호가 각 단계에서 짝을 이루는지 확인하세요.
cannot unmarshal필드 값의 유형문자열, 숫자, 불리언, 객체, 배열을 구분하세요. 문장 부호만 고치면 해결되는 것은 아닙니다.
검사는 통과했지만 시작 후 종료됨실행 시 필요한 리소스포트 바인딩, 파일 권한, 실제로 불러온 경로를 계속 확인하세요. 검사 통과가 수신 대기 성공을 보장하지는 않습니다.

행 번호는 대개 파서가 문제를 발견한 위치를 가리킬 뿐, 오류가 처음 생긴 곳을 뜻하지는 않습니다. 24행에 오류가 표시되면 23행도 함께 확인하세요. 인증 정보가 포함된 설정 파일 전체를 온라인 포맷터에 붙여 넣지 마세요. 로컬 편집기의 괄호 짝 확인 기능과 코어 검사 명령만으로도 대개 충분합니다.

결론: 검사 결과는 해당 파일에만 유효합니다

직접 검사했을 때는 성공했는데 클라이언트에서 실패한다면 시작 로그의 설정 경로, 코어 경로, 작업 디렉터리를 바로 비교하세요. 다른 설정 파일의 검사 결과만으로 클라이언트가 현재 생성한 설정도 올바르다고 판단하지 마세요.

4. 필드 오류: 계층을 따라 확인하고 철자만 보지 않기

JSON 문법을 통과한 뒤에도 Xray 설정 구조에 맞아야 합니다. inbounds와 outbounds는 배열입니다. 프로토콜별 매개변수는 해당 settings에 넣고, 전송 및 보안 매개변수는 대개 streamSettings에 넣습니다. 필드를 잘못된 계층에 배치하면 JSON 문법이 올바르더라도 설정을 구성하지 못하거나 값이 적용되지 않을 수 있습니다.

한 코어의 설정 조각을 다른 형식의 설정 파일에 그대로 붙여 넣지 마세요. v2rayN의 노드 편집 폼은 전체 Xray JSON과 다릅니다. 클라이언트는 노드, 라우팅, 전역 옵션을 바탕으로 실행 설정을 생성합니다. 특히 VLESS와 VMess의 프로토콜 매개변수를 구분해야 합니다. 둘 다 사용자 식별자를 사용한다고 해서 settings 블록 전체를 서로 바꿔 쓸 수는 없습니다.

오류: unknown config id

원인 및 해결 방법: 오류 메시지에 나온 프로토콜이나 설정 유형을 현재 빌드에서 인식하지 못한 것입니다. 이어지는 구체적인 값을 확인해 표기, 계층, 코어 지원 범위를 점검하세요. JSON 괄호만 수정해서는 해결되지 않습니다.

오류: no such file or directory

원인 및 해결 방법: 설정에서 참조하는 파일이나 시작에 필요한 리소스가 없습니다. 오류 메시지에서 구체적인 경로를 확인하고 실행 환경에 파일이 실제로 있는지 점검하세요. 규칙 데이터 관련 오류라면 먼저 리소스 경로를 확인하고, 그다음 라우팅 변경을 검토하세요.

알 수 없는 필드가 일부 파싱 경로에서 무시될 수도 있으므로 항상 오류가 발생하는 것은 아닙니다. 따라서 오류가 없다는 것은 현재 검사를 통과했다는 뜻일 뿐, 직접 입력한 모든 필드가 적용되었다는 의미는 아닙니다. 라우팅을 변경했다면 대상 도메인을 지정해 아웃바운드 선택을 다시 확인하세요. 웹페이지 하나가 열린다는 사실만으로 전체 설정을 검증하지 마세요.

5. 최소 설정: 환경 문제와 노드 문제 분리

전체 설정이 길다면 아래 파일을 check.json으로 저장해 먼저 검사하세요. 로컬 127.0.0.1:10818에서 SOCKS 인바운드만 제공하고 목적지에 직접 연결합니다. 원격 프록시 노드는 포함하지 않으므로 구독이 작동하는지 확인하는 데 사용할 수 없습니다. 현재 Xray가 설정을 읽고 아웃바운드를 구성하며 로컬 포트를 열 수 있는지 확인하기 위한 파일입니다.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-check",
      "listen": "127.0.0.1",
      "port": 10818,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": false
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    }
  ]
}
  1. 먼저 .\xray.exe run -test -config .\check.json을 실행하세요. 실패하면 출력 내용을 보관하고 실제 노드 매개변수를 추가하지 않은 채 파일 내용과 현재 코어를 먼저 확인하세요.
  2. 검사를 통과하면 .\xray.exe run -config .\check.json을 실행하세요. 프로세스가 계속 실행되고 127.0.0.1:10818이 수신 대기 중인지 확인해야 바인딩 검사에 통과한 것입니다. 창에 새 출력이 잠시 없다고 멈춘 것은 아닙니다.
  3. Ctrl+C를 눌러 검사 프로세스를 중지한 다음 원래 설정을 단계별로 복구하세요. 노드 아웃바운드, 전송 및 보안 설정, 라우팅과 규칙 데이터 순으로 추가하고, 각 단계를 복구할 때마다 검사하세요.
  4. 최소 설정은 시작되는데 특정 블록을 복구한 뒤 실패한다면 새로 추가한 필드나 의존성이 문제 범위입니다. 한 번에 노드, 포트, 코어를 모두 바꾸지 마세요.

6. 버전 호환성: 실제로 실행되는 파일 확인

클라이언트 버전과 코어 버전은 별개입니다. v2rayN 프로그램만 업데이트했다고 Xray도 업데이트된 것은 아닙니다. 코어 파일을 직접 덮어써도 클라이언트가 그 파일을 호출한다는 보장은 없습니다. 시작 로그의 경로와 xray.exe version 출력, 프로세서 아키텍처를 확인하세요.

새 필드나 전송 유형, 변경된 기존 필드는 코어 버전에 따라 지원 여부가 달라질 수 있습니다. 이 경우 시작 가능한 버전과 설정 사본을 먼저 보관한 뒤 클라이언트의 업데이트 기능이나 다운로드 페이지에서 호환되는 구성 요소를 받으세요. 설정을 억지로 시작시키려고 필드를 계속 삭제해 원래 필요한 연결 동작을 바꾸지 마세요.

결론: 재현 가능한 진단 정보를 보관하세요

클라이언트 버전, 실제 코어 버전, 설정을 불러온 경로, 최초 오류 메시지 전체, 마지막 변경 사항을 기록하세요. 최소 설정이 시작된다면 어떤 설정 블록을 추가한 뒤 실패했는지도 남기세요. 이런 정보가 단순히 “시작 실패”라고 표시된 스크린샷보다 원인을 찾는 데 더 유용합니다.

7. 코어 시작 실패 관련 자주 묻는 질문

생성된 설정을 수정했는데 재시작 후 원래대로 돌아오는 이유는 무엇인가요?

v2rayN은 노드와 전역 옵션에 따라 실행 설정을 다시 생성합니다. 「설정」→「매개변수 설정」, 노드 편집, 라우팅 설정에서 원본 값을 수정하세요. JSON 파일 전체를 직접 작성해야 한다면 클라이언트의 사용자 설정 기능을 사용하고 실제로 불러온 파일 경로를 확인하세요.

설정 검사는 통과했는데 왜 시작 실패가 표시되나요?

run -test 통과가 수신 대기 성공을 의미하지는 않습니다. 실제 인바운드 포트를 확인하고, 클라이언트가 명령줄과 같은 코어와 설정을 사용하는지 점검하세요. 이어서 로그 파일과 규칙 데이터 등의 경로에 접근할 수 있는지 확인하고, 마지막으로 다른 시스템 환경 요인을 살펴보세요.

노드를 바꾸면 해결되는데 구독에 문제가 있는 건가요?

반드시 그렇지는 않습니다. 노드마다 프로토콜과 전송 매개변수가 다를 수 있고, 클라이언트에서 서로 다른 코어에 연결될 수도 있습니다. 실패한 노드는 그대로 둔 채 노드 편집 창에서 프로토콜, 전송, 보안 유형, Core 선택을 비교해 어떤 매개변수 조합이 설정 오류를 일으키는지 확인하세요. 구독 그룹 전체를 먼저 삭제할 필요는 없습니다.

관리자 권한으로 실행하니 해결됐는데 계속 이렇게 사용해야 하나요?

먼저 일반 로컬 수신 대기에서 실패한 것인지 TUN 초기화에서 실패한 것인지 확인하세요. 일반적인 로컬 루프백의 고번호 포트에는 보통 관리자 권한이 필요하지 않습니다. 파일이나 폴더 권한이 문제라면 해당 접근 권한을 바로잡으세요. TUN 권한이 실제로 필요할 때만 클라이언트 안내에 따라 권한을 부여하고, 모든 오류를 관리자 권한으로 덮지 마세요.

v2rayN 다운로드