· 문제 해결 · 약 12분

v2rayN 코어 실행 문제 해결

v2rayN 코어 실행에 실패했을 때 로그를 읽는 방법을 알아봅니다. 포트 충돌, JSON 문법 오류, 알 수 없는 필드, geo 파일 누락 사례별로 원인을 찾고 해결하는 방법을 소개합니다.

핵심 내용

v2rayN은 실행되지만 코어를 시작하자마자 종료되거나 설정을 불러오지 못한다는 메시지가 반복되는 경우에 적용할 수 있습니다. 먼저 실제로 실행된 코어와 설정 파일 경로를 확인한 뒤, 오류의 마지막 부분을 살펴보며 리스닝 실패, JSON 파싱 실패, 호환되지 않는 설정 필드, 라우팅 데이터 로드 실패를 구분하세요. 한 번에 한 가지 문제만 수정하고 같은 설정으로 다시 테스트해야 코어 실행 문제와 노드 연결 문제를 혼동하지 않습니다.

코어 실행 실패와 노드 연결 실패 구분하기

v2rayN은 클라이언트 인터페이스이며, Xray나 V2Ray 같은 코어가 설정을 읽고 로컬 포트를 열어 연결을 처리합니다. 메인 창에 서버 목록이 표시된다고 코어가 정상 실행 중인 것은 아닙니다. 시스템 프록시가 켜져 있어도 해당 로컬 포트에서 리스닝 중이라는 뜻은 아닙니다. 브라우저의 “사이트에 연결할 수 없음” 메시지가 아니라 이번 실행에서 생성된 로그부터 확인하세요.

로그에서 설정을 읽은 직후 프로세스가 종료되고 Failed to start, failed to load config 또는 포트 바인딩 실패가 나타난다면 로컬 설정을 먼저 확인하세요. 코어가 계속 실행되고 로컬 프록시 포트도 리스닝 중인데 대상에 접속할 때만 시간 초과, 인증서 오류 또는 연결 거부가 발생한다면 노드 주소, TLS, 네트워크 경로를 점검해야 합니다. 로그 문구는 코어 버전에 따라 달라질 수 있으므로 아래 예시와 문장 전체가 정확히 일치할 필요는 없습니다.

이번 실행 로그와 실제 설정 파일 경로 기록하기

먼저 v2rayN의 「도움말」→「정보」에서 클라이언트 버전을 기록하고, 시작 로그에서 코어 이름과 버전, 설정 파일 경로를 확인하세요. 데스크톱 버전과 WPF 버전은 일부 메뉴 위치가 다릅니다. 이 문서에서 다루는 옵션은 「설정」→「매개변수 설정」에서 찾을 수 있으며, 세부 항목 이름은 현재 인터페이스를 기준으로 확인하세요. 화면에 표시된 클라이언트 버전만으로 코어 버전을 추정할 수는 없습니다. 설치 폴더에서 이름이 같은 파일을 찾았다고 해서 이번 실행에서 그 파일을 불러왔다고 단정하지 마세요.

  1. 이전 로그 보관하기

    현재 오류를 로컬 텍스트 파일에 복사한 다음 메인 창의 로그 표시 영역을 지우세요. 현재 서버를 다시 선택해 활성 서버로 지정하고 코어를 재시작한 뒤, 이번 작업에서 생성된 연속 로그만 보관하세요.

  2. 코어 확인하기

    시작 로그에서 실행 파일 이름과 버전을 확인하세요. 코어 선택을 변경했다면 「설정」→「매개변수 설정」의 코어 관련 항목을 열어 확인하고, 실제 시작 출력 내용을 기준으로 판단하세요.

  3. 파일 경로 찾기

    설정을 불러온 전체 경로를 기록하세요. 일반 노드에서 생성한 설정과 사용자 지정 설정은 처리 방법이 다릅니다. 오류가 난 파일을 진단용으로 복사해 두고, 클라이언트의 영구 설정 파일을 바로 덮어쓰지 마세요.

  4. 오류 마지막 부분 확인하기

    같은 오류 흐름을 따라 바깥쪽 안내부터 마지막 원인까지 확인하세요. 예를 들어 “설정 로드 실패” 뒤에 나오는 “파일을 찾을 수 없음”이 실제 해결 대상입니다. 처음 표시된 실패 메시지만 잘라서 보지 마세요.

일반 노드의 실행 설정은 활성 서버를 다시 지정하거나 라우팅을 바꾸거나 재시작할 때 다시 생성될 수 있습니다. 생성된 config.json을 직접 수정하면 “고쳤는데 다시 원래대로 돌아오는” 일이 자주 발생합니다. 원인을 확인한 뒤 노드 편집, 라우팅 설정 또는 매개변수 설정에서 원본을 수정하세요. 사용자 지정 설정을 명시적으로 사용하는 경우에만 해당 사용자 지정 파일을 직접 관리하면 됩니다.

포트 충돌: 리스너를 찾아 포트 변경하기

가장 흔한 원인은 다른 클라이언트 인스턴스나 종료 후 남은 코어가 로컬 포트를 차지하고 있는 경우입니다. 아래에서는 Windows의 127.0.0.1:10808을 예로 듭니다. 이는 문제 해결을 위한 예시일 뿐이며 모든 버전에서 같은 포트를 사용한다는 뜻은 아닙니다. 「설정」→「매개변수 설정」에서 실제 로컬 리스닝 포트를 확인하세요. 현재 인터페이스에서 SOCKS, HTTP, 혼합 포트를 따로 설정한다면 각 항목을 확인하고 예시 숫자를 그대로 사용하지 마세요.

10808
이 문서의 리스닝 포트 예시
10809
이 문서의 대체 포트 예시
65535
TCP 포트 번호 최댓값

오류: bind: address already in use

원인 및 해결: 지정한 주소와 포트를 이미 다른 프로세스가 사용 중입니다. Windows에서는 Only one usage of each socket address로 표시될 수도 있습니다. 포트를 사용 중인 프로세스를 확인하고 중복 실행된 인스턴스를 정상 종료하거나 로컬 리스닝 포트를 변경한 뒤 코어를 재시작하세요.

PowerShell에서 아래 명령을 실행하면 TCP 리스닝 연결만 조회할 수 있습니다. 원격 연결에 우연히 같은 포트 번호가 나타난 경우와 혼동하지 않도록 해줍니다. 출력된 OwningProcess는 프로세스 ID입니다. 먼저 프로세스 이름과 프로그램 경로를 확인한 다음 종료 여부를 결정하세요.

Get-NetTCPConnection -State Listen -LocalPort 10808 |
  Select-Object LocalAddress, LocalPort, OwningProcess

Get-NetTCPConnection -State Listen -LocalPort 10808 |
  ForEach-Object { Get-Process -Id $_.OwningProcess }

결과가 없다면 조회 시점에 해당 포트의 TCP 리스너가 발견되지 않았다는 뜻일 뿐, 설정이 완전히 올바르다는 의미는 아닙니다. 로그에 표시된 실제 주소, 다른 UDP 충돌 여부, access permissions 같은 시스템 제한도 확인하세요. 포트를 10809로 바꿨다면 프록시를 수동으로 설정한 브라우저와 터미널도 함께 변경해야 합니다. 클라이언트가 시스템 프록시를 관리한다면 시스템 프록시를 다시 설정해 포트를 갱신하세요. 테스트 전에 대체 포트도 사용 중이 아닌지 확인하세요.

JSON 문법 오류: 구조를 먼저 고친 뒤 설정값 확인하기

JSON 파싱 오류는 사용자 지정 설정을 직접 작성하거나 일부 설정을 복사하거나 라우팅 규칙을 편집한 뒤 발생하는 경우가 많습니다. 객체 항목 사이의 쉼표 누락, 한글 인용 부호 사용, 괄호를 닫지 않은 경우, 마지막 항목 뒤에 쉼표를 붙인 경우가 대표적입니다. 주석 같은 확장 문법은 로더마다 지원 여부가 다릅니다. 여러 버전에서 문제를 진단할 복사본은 먼저 엄격한 JSON 형식으로 작성하세요.

오류: invalid character '}' looking for beginning of object key string

원인 및 해결: 객체를 닫기 전의 구조가 파서의 요구 사항에 맞지 않습니다. 마지막 항목 뒤에 쉼표를 붙인 경우가 흔합니다. 오류가 난 위치와 바로 위 줄을 확인하고 불필요한 구분자를 삭제한 뒤 괄호 짝도 점검하세요.

오류: unexpected EOF

원인 및 해결: 파일 끝에 도달했지만 내용이 아직 완성되지 않았습니다. 닫는 괄호가 빠졌거나 파일이 완전히 저장되지 않았을 수 있습니다. 파일의 마지막 부분을 확인하고 설정을 온전히 복구한 다음 문법을 검사하세요.

아래는 숫자 포트, 문자열의 인용 부호, 배열의 닫는 방법을 보여 주는 올바른 부분 객체이며, 바로 실행할 수 있는 완전한 설정 파일은 아닙니다. 규칙 조각을 기존 파일에 넣을 때는 어느 상위 필드에 속하는지 확인하세요. 완전한 JSON 객체 두 개를 그대로 이어 붙이면 안 됩니다.

{
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ]
}

알 수 없는 필드와 지원되지 않는 설정값

JSON 파싱에 성공했다는 것은 파일 구조가 올바르다는 뜻일 뿐, 코어가 모든 프로토콜과 전송 방식 또는 매개변수를 지원한다는 뜻은 아닙니다. v2rayN 인터페이스 설정 파일, V2Ray 설정 파일, Xray 설정 파일은 서로 다른 데이터 형식입니다. 클라이언트가 저장하는 설정 파일을 코어 설정으로 사용하거나 다른 코어용 설정을 그대로 가져오면 로드 실패 또는 비정상 동작이 발생할 수 있습니다.

알아둘 점: 알 수 없는 필드가 항상 오류를 일으키는 것은 아닙니다. 일부 파싱 경로는 인식하지 못한 키를 무시합니다. “unknown field”가 없다고 해서 필드 이름의 철자가 맞다고 단정할 수 없습니다. 더 흔한 원인은 특정 설정값이 지원되지 않는 경우입니다. 예를 들어 unknown transport protocol이 표시되면 JSON 구두점만 고칠 것이 아니라 전송 방식과 실제 실행 중인 코어를 확인해야 합니다.

오류: unknown field

원인 및 해결: 엄격한 디코딩 과정에서 인식하지 못한 필드가 거부되었습니다. 뒤에 표시된 필드 이름을 기록하고 해당 필드의 계층, 철자, 현재 코어의 문서를 확인하세요. 클라이언트에서 가져오는 단계에서 발생한 오류라면 노드, 사용자 지정 코어 설정, 클라이언트 설정 중 무엇을 가져왔는지 먼저 확인하세요.

오류: unknown transport protocol

원인 및 해결: 현재 코어에서 설정에 지정된 전송 식별자를 인식하지 못합니다. 노드 편집 화면의 전송 설정과 코어 버전을 확인하세요. 오류를 없애기 위해 아무 전송 방식으로나 바꾸지 마세요.

VMess와 VLESS는 프로토콜 이름이지, 시험 삼아 서로 바꿔 볼 수 있는 해결 옵션이 아닙니다. 서버 프로토콜, 전송 방식, 보안 매개변수는 서로 맞아야 합니다. 구독에서 가져온 일반 노드라면 유효한 설정을 다시 가져오고 서버 요구 사항을 확인하세요. 사용자 지정 설정이라면 원본 파일을 보관하고 의심되는 필드를 하나씩 현재 코어의 지원 범위와 비교하세요.

geo 파일 누락: 파일, 경로, 분류 이름 확인하기

라우팅에서 geoip:cn 또는 geosite:cn을 사용할 때 기존 DAT 데이터를 쓰는 설정은 보통 해당하는 geoip.dat, geosite.dat 파일이 필요합니다. 오류 흐름에는 먼저 “라우팅 규칙 생성 실패”가 표시되고 마지막에 데이터 파일을 열 수 없거나 분류를 찾을 수 없다는 내용이 나올 수 있습니다. 앞부분은 결과이고, 파일을 추가할지 규칙을 수정할지는 마지막 원인으로 판단해야 합니다.

오류: failed to load GeoIP

원인 및 해결: GeoIP 데이터를 불러오지 못했습니다. 이어지는 로그에서 경로와 시스템 오류를 확인하세요. no such file or directory라면 실제 리소스 디렉터리를 점검하고 필요한 geoip.dat 파일을 복구하세요.

오류: failed to load geosite

원인 및 해결: 도메인 분류 데이터를 읽지 못했거나 요청한 분류가 파일에 없습니다. 파일이 없는 경우, 읽을 수 없는 경우, 분류가 누락된 경우를 구분한 뒤 각각 리소스 경로, 접근 권한, 규칙의 분류 이름을 수정하세요.

  1. 로그에 표시된 전체 리소스 경로를 복사하세요. 작업 디렉터리가 프로그램 디렉터리와 같다고 가정하지 마세요. 사용자 지정 실행 방식과 리소스 경로 설정에 따라 검색 위치가 달라질 수 있습니다.
  2. 파일이 없다면 클라이언트의 리소스 업데이트 메뉴와 업데이트 로그를 확인하세요. 필요한 경우 전체 클라이언트 패키지에서 관련 구성 요소를 복구한 뒤 대상 디렉터리에 파일이 실제로 저장됐는지 확인하세요.
  3. 파일은 있지만 분류가 없다면 규칙의 분류 이름과 데이터 출처를 확인하세요. 모든 데이터 파일에 같은 분류가 들어 있는 것은 아닙니다. 파일 이름을 바꿔도 분류 데이터가 새로 생기지는 않습니다.
  4. 해당 분류를 참조하는 사용자 지정 규칙을 잠시 비활성화한 뒤 시작할 수 있다면 문제 범위를 규칙과 데이터 의존성으로 좁힐 수 있습니다. 실제 사용을 재개하기 전에 데이터를 보완하고 라우팅이 제대로 되는지 다시 확인하세요.

수정 후 같은 순서로 다시 테스트하기

한 번에 변수 하나만 바꾸고 코어를 다시 시작한 뒤 새 로그를 저장하세요. 노드 변경, 포트 변경, 코어 교체, 라우팅 삭제를 한꺼번에 하면 문제가 해결되어도 실제 원인을 알 수 없습니다. 사용자 지정 Xray 설정은 실제로 함께 제공된 Xray 실행 파일로 로드 테스트할 수 있습니다. 아래 명령은 진단용 복사본이 있는 디렉터리에서 실행하며 파일 이름은 config.json입니다.

.\xray.exe run -test -config .\config.json

이 명령은 해당 명령줄 형식을 지원하는 Xray용입니다. 다른 코어는 자체 도움말을 먼저 확인하고 그대로 따라 하지 마세요. 테스트 환경은 클라이언트와 동일한 리소스를 사용해야 합니다. geo 파일 검색 경로가 달라 추가 오류가 발생할 수 있기 때문입니다. 설정 테스트를 통과해도 원격 연결이 정상이라는 뜻은 아니며, 실제 실행 중 포트를 바인딩할 수 있다는 보장도 없습니다. 클라이언트에서 다시 확인하세요.

코어 실행 오류 자주 묻는 질문

config.json을 수정했는데 다음 실행에서 왜 다시 오류가 나나요?

먼저 해당 파일이 클라이언트에서 생성한 실행 설정인지 확인하세요. 일반 노드는 노드 편집, 라우팅 설정 또는 「설정」→「매개변수 설정」에서 원본을 수정한 뒤 활성 서버로 다시 지정해 설정을 생성해야 합니다. 사용자 지정 설정이라면 실제로 불러오는 경로를 확인하고 백업 파일을 수정한 것은 아닌지 점검하세요.

구독을 업데이트하면 코어 실행 오류가 해결되나요?

오류 원인이 구독 노드의 매개변수일 때만 해결될 가능성이 있습니다. 리스닝 포트 충돌, JSON 파일 손상, 로컬 geo 파일 누락은 구독을 반복해서 업데이트해도 해결되지 않습니다. 오류 흐름의 마지막 내용을 확인해 먼저 문제 유형을 구분하세요.

포트가 비어 있는데도 bind 오류가 나는 이유는 무엇인가요?

로그에 표시된 리스닝 주소가 이 컴퓨터의 주소인지, 시스템에서 해당 포트를 제한하는지 확인하세요. cannot assign requested address가 포함되어 있다면 주소를 먼저 수정하고, 권한 거부가 표시되면 시스템 제한을 확인하세요. 모든 bind 오류를 기존 프로세스의 포트 점유로 단정하지 마세요.

로그를 공유해 도움을 요청할 때 어떤 내용을 남겨야 하나요?

클라이언트 버전, 코어 버전, 운영체제, 이번 실행부터 종료까지의 연속 로그, 최근 변경 사항을 함께 제공하세요. 구독 링크, 사용자 식별자, 인증 정보는 가리고 오류 필드 이름, 로컬 포트, 경로 구조는 남겨야 자격 증명을 노출하지 않고도 문제를 파악할 수 있습니다.

클라이언트 다운로드