2026-08-09 · 문제 해결 · 약 10분

V2Ray 코어 시작 오류 해결: v2rayN 로그로 JSON 설정 오류 찾기

시작을 눌러도 연결되지 않나요? 코어 로그에서 포트 충돌, 필드 오타, 라우팅 규칙 형식, geo 리소스 누락을 찾아 해결하는 방법을 안내합니다.

핵심 내용

먼저 코어 프로세스가 실제로 종료됐는지 확인한 뒤, 이번 시작 로그에서 처음 나타난 구체적인 오류를 찾으세요. 이 글은 v2rayN의 설정 로드 및 시작 오류를 대상으로 합니다. JSON 파싱, 필드 의미, 라우팅 및 리소스 로드, 포트 바인딩 순으로 점검하면 유효한 로그를 보존하고 한 번에 한 항목씩 수정할 수 있으며, 시작 실패와 시작 후 연결 실패도 구분할 수 있습니다.

먼저 구분하기: 코어 종료인가, 연결 실패인가

웹페이지가 열리지 않는다고 해서 V2Ray 코어 시작에 실패한 것은 아닙니다. v2rayN은 노드, 구독, 프록시 설정을 관리하는 클라이언트입니다. 실제 연결은 선택한 코어가 처리하며, Xray 또는 V2Fly일 수 있습니다. 메인 창이 열려 있다는 사실만으로 클라이언트가 실행 중임을 알 수 있을 뿐, 코어가 정상적으로 시작됐다고 단정할 수는 없습니다.

시작 오류는 보통 설정을 읽거나 인바운드·아웃바운드를 구성하거나, 규칙 리소스를 로드하거나, 로컬 포트를 바인딩할 때 발생합니다. 코어가 이미 로컬 포트를 열어 둔 뒤 노드 연결 시간 초과나 TLS 핸드셰이크 오류가 나타난다면 네트워크와 노드 설정을 점검해야 합니다. 로컬 JSON 문법 오류를 해결하려고 구독을 계속 업데이트하지 마세요.

설정 읽기 규칙 구성 리소스 로드 포트 대기 연결 처리
로그 또는 증상우선 판단다음 단계
설정 파싱 오류 후 프로세스가 즉시 종료됨설정 로드 실패오류가 가리키는 파일과 필드 확인
로컬 10808 포트 바인딩 실패포트 대기 설정 실패해당 포트를 사용 중인 프로세스 확인
시작 로그가 표시되고 실제 설정된 포트가 열려 있음코어가 시작됐을 가능성이 큼시스템 프록시, 라우팅, 아웃바운드 연결 확인
웹페이지에 접속할 때만 시간 초과 발생실행 중 연결 오류노드 주소, 포트, 전송 매개변수 확인

표의 10808은 점검 예시일 뿐입니다. 실제 포트는 「설정」→「매개변수 설정」의 로컬 리스닝 설정과 생성된 설정 파일을 기준으로 확인하세요. 해당 포트가 열려 있어도 다른 클라이언트가 사용 중일 수 있으므로 프로세스도 함께 확인해야 합니다.

한 번의 시작 로그 전체를 보관하세요

설정을 바꾸기 전에 로그부터 남기세요. 로그 끝부분은 흔히 ‘시작 실패’만 요약하며, 실제 원인은 그 앞의 코어 출력에 있습니다. 오류 흐름에서 가장 구체적인 파싱 오류, 파일 읽기 오류 또는 시스템 오류를 찾으세요. 한 줄짜리 메시지보다 같은 시작 과정의 앞뒤 로그가 더 유용합니다.

  1. 환경 기록

    v2rayN 버전, 운영체제, 선택한 코어, 코어 시작 로그에 표시된 버전을 기록하세요. 클라이언트 버전과 코어 버전은 각각 확인해야 하며 서로 대신할 수 없습니다.

  2. 설정 확인

    「설정」→「매개변수 설정」을 열어 로컬 리스닝 포트를 기록하세요. 현재 버전에 「Core 유형」 설정이 있다면 선택 항목도 기록합니다. 화면의 메뉴 구성은 버전에 따라 다를 수 있으므로, 실제 실행된 실행 파일은 이번 로그를 기준으로 확인하세요.

  3. 한 번 재현

    메인 화면에서 로그 또는 정보 출력 영역을 열고 현재 시간을 기록한 다음, 대상 노드에서 「활성 서버로 설정」을 한 번 실행하세요. 로그가 이번 시작 과정에 해당하는지 확인하고, 앞서 속도 테스트로 발생한 임시 코어 로그와 섞지 마세요.

  4. 오류 흐름 저장

    코어 버전 줄부터 종료 메시지까지 저장하세요. 설정 경로, 오류가 발생한 필드, 시스템 오류 원문을 보존합니다. 다른 사람과 공유하기 전에는 구독 토큰, 노드 인증 정보, 개인 디렉터리 이름을 가리세요.

  5. 한 번에 한 항목씩 수정

    설정 종류를 한 가지만 바꾼 뒤 다시 시작하세요. 오류가 파싱 실패에서 포트 충돌로 바뀌었다면 다음 단계로 넘어간 것입니다. 두 로그를 같은 원인으로 오해하지 마세요.

JSON 문법: 쉼표, 따옴표, 데이터 형식 확인

JSON 파싱 오류는 설정 필드가 작동하기 전에 발생합니다. 표준 JSON에서는 객체 키와 문자열에 영문 큰따옴표를 사용해야 하며, 마지막 항목 뒤에 쉼표를 붙이면 안 됩니다. 일부 코어 로더가 주석 같은 확장 문법을 허용하더라도 모든 도구가 같은 문법을 지원한다고 가정하지 마세요.

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

원인: 객체의 마지막 항목 뒤에 쉼표가 남아 있어 파서가 다음 키를 기다리는 경우가 많습니다.

해결: 오류 위치 바로 앞 줄을 확인하고 닫는 중괄호 앞의 불필요한 쉼표를 삭제한 뒤, 사용 중인 코어로 설정을 테스트하세요.

오류: unexpected EOF

원인: 파일 끝까지 읽었는데 내용이 완성되지 않았습니다. 괄호가 닫히지 않았거나 파일이 잘렸을 수 있습니다.

해결: 파일 끝의 중괄호, 대괄호, 큰따옴표를 확인하고 편집기에서 파일 전체가 저장됐는지 점검하세요.

오류: cannot unmarshal string into Go value of type uint16

원인: 정수를 요구하는 필드에 문자열이 들어갔습니다. 전체 로그에는 해당 필드나 구조 정보가 함께 표시되는 경우가 많습니다.

해결: 현재 코어의 필드 정의에 맞게 데이터 형식을 수정하세요. 모든 숫자에 일괄적으로 따옴표를 붙이거나 문자열의 따옴표를 모두 제거하지 마세요.

아래 예시는 표준 JSON에서 마지막 쉼표가 문제가 되는 경우만 보여 줍니다. 바로 실행할 수 있는 완전한 프록시 설정은 아닙니다. 코어가 포트를 여러 형식으로 허용하더라도 JSON 객체의 경계는 올바르게 작성해야 합니다.

{
  "listen": "127.0.0.1",
  "port": 10808,
}

위의 10808 뒤에 쉼표가 하나 더 있습니다. 수정하면 다음과 같습니다.

{
  "listen": "127.0.0.1",
  "port": 10808
}

필드와 라우팅: 파싱된다고 사용할 수 있는 것은 아닙니다

JSON 형식이 올바르다는 것은 내용을 읽을 수 있다는 뜻일 뿐, 코어가 해당 프로토콜, 전송 옵션, 라우팅 규칙을 인식한다는 뜻은 아닙니다. 필드 이름은 대소문자를 구분하는 경우가 많습니다. 클라이언트 설정, 구독 텍스트, 코어 실행 설정은 구조가 서로 다르므로 구독 내용을 코어 JSON으로 바로 사용하면 안 됩니다.

필드 이름을 잘못 써도 ‘알 수 없는 필드’ 오류가 발생하지 않을 수 있습니다. 일부 로더는 알 수 없는 키를 무시하므로, 필수 필드가 빠지거나 옵션이 기본값으로 돌아갈 수 있습니다. 따라서 테스트를 통과했다는 이유만으로 사용자 지정 필드가 모두 적용됐다고 판단하지 마세요.

확인 항목세부 점검 사항수정 방향
프로토콜 및 전송protocol과 전송 설정이 현재 코어에서 지원되는지 확인선택한 코어를 확인하고 다른 코어의 전체 설정을 그대로 적용하지 마세요
아웃바운드 태그outboundTag 값이 실제 아웃바운드의 tag와 일치하는지 확인원래 대소문자에 맞춰 이름을 통일하고, 테스트 통과 후에도 트래픽이 의도한 경로로 가는지 확인하세요
라우팅 규칙routing.rules가 배열인지, 각 규칙에 유효한 매칭 조건이 있는지 확인실수로 들어간 빈 규칙을 삭제하고 domain, ip 등의 필드 형식을 확인하세요
리소스 참조geosite:cn, geoip:private에 필요한 파일과 태그가 있는지 확인리소스 버전, 경로, 참조 태그가 서로 맞도록 조정하세요

아래는 자주 쓰는 라우팅 설정 예시이며, 이미 완성된 설정에 추가해야 합니다. 태그가 direct인 아웃바운드가 이미 있어야 하고, 코어가 해당 태그를 포함한 리소스 파일을 읽을 수 있어야 합니다.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["geosite:cn"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

정리: 먼저 규칙을 줄이고 분할 라우팅을 복원하세요

현재 라우팅 설정을 백업한 뒤 클라이언트 기본 간소화 설정으로 잠시 전환하세요. 같은 노드가 시작된다면 사용자 지정 규칙을 묶음별로 복원합니다. 한 번에 한 묶음씩 추가해 오류를 일으키는 리소스 참조나 규칙 필드를 찾아내세요.

시작 후에는 규칙 순서도 확인해야 합니다. 더 넓은 범위의 규칙이 앞에 있으면 트래픽을 먼저 매칭해 뒤의 세부 규칙이 적용되지 않을 수 있습니다. 이는 분할 라우팅 로직 문제이므로 JSON 파싱 오류와 따로 다뤄야 합니다. 관련 개념은 심화 설정의 라우팅 설명을 참고하세요.

포트 충돌: 프로세스를 확인하고 먼저 강제 종료하지 마세요

로컬 리스닝 충돌은 원격 노드 포트와 관계가 없습니다. 코어가 127.0.0.1:10808에 바인딩하려 할 때 다른 프로세스가 해당 주소와 포트를 사용 중이면 시작하지 못할 수 있습니다. 다른 v2rayN 인스턴스가 실행 중이거나 이전에 시작한 코어가 종료되지 않은 경우가 흔합니다.

오류: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.

원인: Windows에서 이미 사용 중인 리스닝 주소에 중복으로 바인딩할 수 없습니다. 전체 오류에는 보통 사용 중인 주소와 포트가 표시됩니다.

해결: 리스닝 프로세스를 확인한 뒤 중복 실행된 인스턴스를 정상 종료하거나, 로컬 포트를 바꾸고 해당 포트를 사용하는 앱의 설정도 함께 수정하세요.

오류: bind: address already in use

원인: Linux 등의 환경에서 같은 리스닝 주소와 포트를 이미 사용 중입니다.

해결: 시스템 포트 조회 도구로 사용 중인 프로세스를 확인하세요. 같은 설정을 사용하는 코어를 두 개 동시에 실행하지 마세요.

Windows PowerShell에서 아래 두 명령을 실행하면 TCP 10808을 리스닝 중인 프로세스와 프로세스 이름을 확인할 수 있습니다. 프로세스를 종료하지는 않습니다. 설정에서 다른 포트를 사용한다면 10808을 로그에 표시된 값으로 바꾸세요.

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

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

geo 리소스: 파일 누락과 태그 누락 구분

geosite.dat은 도메인 분류를, geoip.dat은 IP 분류를 제공합니다. 규칙에서 이러한 리소스를 참조할 때 파일을 찾을 수 없거나 읽을 수 없거나 필요한 태그가 파일에 없으면 설정 구성이 중단될 수 있습니다. 노드를 바꿔도 로컬 리소스 읽기 오류는 해결되지 않습니다.

오류 예시: failed to load geosite

원인: 도메인 리소스를 불러오지 못했습니다. 이어지는 오류 내용에서 파일 읽기 문제인지 분류 태그가 없는 것인지 확인할 수 있습니다.

해결: 전체 로그에서 경로와 태그를 확인한 뒤 리소스를 복구하거나 규칙 참조를 수정하세요. 이 한 줄만 보고 파일이 손상됐다고 판단하지 마세요.

오류 예시: no such file or directory

원인: 로그에 표시된 파일이 없습니다. 경로가 실제로 geo 파일을 가리키는 경우에만 리소스 누락으로 분류하세요.

해결: 리소스 디렉터리와 실제 실행 위치를 확인하고 해당 파일을 복구한 뒤, 실행 프로세스에 파일 읽기 권한이 있는지 확인하세요.

  1. 경로 확인. 오류에 표시된 파일 이름과 디렉터리를 그대로 기록하세요. 클라이언트에서 실행할 때와 터미널에서 직접 실행할 때 작업 디렉터리나 리소스 검색 설정이 다를 수 있습니다.
  2. 태그 확인. 오류에 특정 목록이 없다고 표시되면 규칙의 분류 이름을 확인하세요. 파일이 존재해도 모든 태그를 사용할 수 있는 것은 아닙니다.
  3. 리소스 복구. 현재 v2rayN 버전에 포함된 리소스 업데이트 기능을 사용하거나 전체 클라이언트 패키지에서 필요한 파일을 복구하세요. 출처와 형식을 알 수 없는 데이터는 섞지 마세요.
  4. 범위 좁혀 검증. 백업한 뒤 해당 분류를 참조하는 규칙을 잠시 제거하고 다시 테스트하세요. 이는 원인을 찾기 위한 조치일 뿐 최종 분할 라우팅 설정이 완성됐다는 뜻은 아닙니다.

같은 코어로 테스트한 뒤 정상 시작 여부 확인

테스트에는 v2rayN에서 실제로 선택한 코어와 설정 사본을 사용해야 합니다. Xray와 V2Fly는 명령줄 실행 방식이 다릅니다. 아래에는 일반적인 Xray 명령과 V2Fly 5.x 하위 명령 형식을 각각 표시했습니다. 실행 전에 해당 프로그램의 도움말에서 옵션을 확인하고 다른 코어의 명령을 그대로 사용하지 마세요.

# PowerShell: 해당 코어 디렉터리에서 실행, config.json은 테스트용 사본
.\xray.exe -test -config .\config.json

# V2Fly 5.x 하위 명령 형식
.\v2ray.exe test -c .\config.json

설정 테스트를 통과해도 실제 시작이 반드시 성공하는 것은 아닙니다. 테스트 모드는 주로 파싱과 구성을 확인하며, 실제 포트 리스닝을 대신하거나 원격 노드 연결을 보장하지 않습니다. 터미널 테스트는 작업 디렉터리 차이로 리소스 경로 오류가 발생할 수도 있으므로 테스트 환경을 클라이언트 실행 환경과 동일하게 맞추세요.

테스트는 통과했는데 왜 시작 오류가 계속 발생하나요?

정상 시작 로그를 다시 확인하세요. 포트 바인딩 오류라면 실제 포트를 사용 중인 프로세스를 조회하고, 리소스 경로 오류가 다시 나타난다면 클라이언트와 터미널의 실행 디렉터리를 비교하세요. ‘설정을 파싱할 수 있음’과 ‘네트워크 연결이 됨’을 혼동하지 마세요.

코어를 바꾼 뒤에만 실패한다면 무엇부터 수정해야 하나요?

먼저 기존 코어로 되돌려 설정이 여전히 작동하는지 확인한 다음 새 코어의 프로토콜 및 전송 지원 여부를 점검하세요. 사용자 지정 설정은 항목별로 조정해야 하며 실행 파일 이름만 바꿔서는 안 됩니다. 일반 노드는 클라이언트에서 선택한 코어와 실제 시작 로그를 확인하세요.

구독을 업데이트한 뒤 모든 노드가 시작되지 않나요?

먼저 공통으로 사용하는 로컬 포트, 라우팅 설정, geo 리소스를 확인하세요. 모든 노드에서 같은 로컬 오류가 발생한다면 공통 설정부터 점검하세요. 특정 유형의 노드만 실패한다면 해당 노드의 프로토콜과 전송 매개변수를 확인하세요.

도움을 요청할 때 어떤 정보를 제공해야 하나요?

클라이언트 및 코어 버전, 한 번의 시작에서 발생한 전체 오류 흐름, 사용자 지정 라우팅 사용 여부, 최근 변경 사항, 실행한 테스트 결과를 제공하세요. 구독 링크의 토큰과 노드 인증 정보를 가리고, 설정 경로에 포함된 개인 정보도 제거하세요.

이 순서대로 점검하면 ‘시작 실패’를 확인 가능한 작은 문제들로 나눌 수 있습니다. 앞의 세 가지를 모두 확인했는데도 특정 사이트에 접속할 수 없다면 DNS, 노드, 라우팅을 점검하세요. 테스트를 통과한 JSON을 계속 수정할 필요는 없습니다. 다른 자주 묻는 문제는 도움말 센터에서 확인할 수 있습니다.

v2rayN 다운로드플랫폼 및 설치 파일 보기