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

V2Ray 코어 실행 오류 해결: 로그로 config.json 오류 찾기

코어 시작 로그를 읽고 JSON 문법 오류, 포트 충돌, 알 수 없는 프로토콜 필드, geo 파일 누락 등 주요 원인을 찾는 방법을 안내합니다.

이 글의 핵심 내용

v2rayN에서 코어가 종료되었다는 알림이 표시되거나, v2rayNG 또는 v2flyNG에서 서비스를 시작할 수 없거나, 코어를 직접 실행할 때 설정 오류가 발생하는 경우에 적용할 수 있습니다. 실제로 불러온 파일과 코어부터 확인한 다음 로그를 따라 파싱, 필드, 리소스, 포트 바인딩 단계별로 점검하세요. 이 글에서는 로컬 확인 명령, 자주 나오는 오류 예시, 수정 후 검증 방법을 소개합니다. 포트와 설정 조각은 문제 해결용 예시이며 노드 연결 정보가 아닙니다.

1. 시작 오류와 연결 오류: 먼저 문제가 발생한 단계 확인

클라이언트 창이 열렸다고 코어까지 실행된 것은 아닙니다. v2rayN은 관리 인터페이스이며, 인바운드와 라우팅, 아웃바운드 처리는 실행된 코어 프로세스가 담당합니다. 시작할 때는 보통 설정을 읽고 프로토콜 및 라우팅 객체를 구성한 다음 로컬 포트를 엽니다. 어느 단계에서든 실패하면 이후 프록시 요청을 처리할 수 없습니다.

설정 읽기필드 파싱리소스 로드포트 바인딩연결 처리

시작 직후 로그에 Failed to start가 표시되면 뒤쪽에서 더 구체적인 원인을 찾으세요. 포트 리스닝이 성공했다는 기록이 있는데 대상에 접속할 때만 시간 초과, 인증 실패 또는 TLS 핸드셰이크 실패가 발생한다면 대개 연결 단계의 문제입니다. 이 경우 JSON의 쉼표를 반복해서 수정해도 해결되지 않으며, 인터페이스에 표시된 “연결 실패”만으로 코어가 시작되지 않았다고 판단해서는 안 됩니다.

2. 전체 로그와 실제로 불러온 설정 확인

마지막 줄의 “프로세스 종료”만 잘라서 보지 마세요. 실제 원인은 같은 오류 체인의 끝부분에 있는 경우가 많으며, > 같은 구분자로 연결되기도 하고 종료 메시지보다 앞에 나타날 수도 있습니다. 코어 버전과 실행 명령부터 종료 원인까지 이번 시작 기록을 연속된 텍스트로 보관하고, 이전 연결 오류와 이번 시작 오류가 섞이지 않도록 하세요.

  1. 현재 상태 보관

    로그 패널에서 이번 시작 기록을 복사하고 현재 사용자 지정 설정을 백업하세요. 로그를 다른 사람에게 전달하기 전에는 구독 주소, 사용자 식별 정보, 비밀번호, 개인 키, 서버 주소 등 민감한 내용을 삭제하세요. 로컬 원본 파일은 그대로 보관합니다.

  2. 코어 확인

    시작 로그에서 실행 파일 이름, 버전, 설정 경로를 확인하세요. v2rayNG는 Xray 코어를, v2flyNG는 V2Fly 코어를 사용합니다. v2rayN은 클라이언트 이름만으로 추측하지 말고 현재 시작 기록을 기준으로 판단하세요.

  3. 설정 확인

    데스크톱 v2rayN에서는 「설정」→「매개변수 설정」에서 로컬 리스닝 관련 항목을 확인할 수 있습니다. 버전에 따라 하위 페이지 이름이 다를 수 있으므로 실제 인터페이스를 기준으로 확인하세요. 인터페이스의 포트와 생성된 설정의 inbounds를 대조합니다.

  4. 별도 테스트

    먼저 클라이언트 프록시 서비스를 중지해 중복 프로세스의 영향을 없애세요. 로그에 표시된 설정 파일을 해당 코어의 설정 테스트 명령으로 검사하세요. 다른 디렉터리에 있는 동명의 config.json 파일을 대신 사용하지 마세요.

아래는 현재 흔히 사용하는 명령 형식이며 코어가 있는 디렉터리에서 실행합니다. 첫 번째 명령은 Windows의 Xray용이고, 두 번째는 test 하위 명령을 지원하는 V2Fly용입니다. 구버전은 명령 매개변수가 다를 수 있으므로 먼저 해당 실행 파일의 help 또는 -h로 확인하세요. 파일 이름에 공백이 있으면 반드시 따옴표로 묶어야 합니다.

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

./v2ray test -c ./config.json

3. JSON 문법 오류: 먼저 문제 문자 위치를 찾고 필드 확인

문법 파싱은 프로토콜 검사보다 먼저 진행됩니다. 노드 주소와 포트가 올바르더라도 이 단계에서 실패하면 코어가 설정을 읽을 수 없습니다. 오류 문자 주변의 따옴표, 쉼표, 중괄호와 대괄호를 우선 확인하세요. 오류 위치는 파서가 멈춘 곳일 뿐, 실제로 빠진 쉼표는 바로 앞 줄에 있을 수 있습니다.

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

원인: 객체 끝에 불필요한 쉼표가 남아 있어 파서가 다음 키 이름을 기다리고 있을 수 있습니다. 해결: 닫는 중괄호 바로 앞 줄을 확인하고 마지막 쉼표를 삭제한 뒤 다시 테스트하세요.

오류: unexpected EOF

원인: 파일이 중간에 끝났습니다. 복사 누락이나 닫는 괄호 누락이 흔한 원인입니다. 해결: 파일 끝을 확인하고 편집기의 괄호 짝 찾기 기능으로 닫히지 않은 객체나 배열을 찾아보세요.

오류: invalid character 'h' looking for beginning of value

원인: 읽어 들인 내용이 따옴표 없는 텍스트로 시작할 수 있습니다. 예를 들어 구독 링크를 JSON으로 잘못 사용한 경우입니다. 해결: 파일 첫 줄을 확인해 코어 설정이 맞는지, 구독 주소나 다운로드 오류 페이지 또는 공유 링크가 아닌지 살펴보세요.

아래는 엄격한 JSON 형식의 인바운드 예시입니다. 문자열, 숫자, 괄호 구조만 보여 주는 조각으로 완전한 설정이 아니며 원본 파일을 대신해 단독으로 사용할 수 없습니다. JSON에는 영문 큰따옴표를 사용합니다. 키 이름에 한글 따옴표를 쓸 수 없으며, 문자열 안의 Windows 경로는 역슬래시를 이스케이프해야 합니다.

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

4. 포트 충돌: 반복해서 재시작하지 말고 프로세스 확인

설정 테스트를 통과해도 실행 시 포트를 반드시 바인딩할 수 있는 것은 아닙니다. 이전 코어 프로세스가 종료되지 않았거나 클라이언트 두 개를 동시에 실행했거나, HTTP와 SOCKS 인바운드가 같은 주소와 TCP 포트를 사용하면 충돌할 수 있습니다. Windows에서는 Only one usage of each socket address라는 오류가 표시될 수 있으며, 다른 시스템에서는 address already in use가 흔히 나타납니다.

10808
이 글의 SOCKS 인바운드 예시 포트
10809
이 글의 HTTP 인바운드 예시 포트
127.0.0.1
로컬에서만 접속할 수 있는 리스닝 주소

이 숫자들은 설명용일 뿐 모든 버전의 기본값은 아닙니다. 먼저 「설정」→「매개변수 설정」에서 실제 포트를 확인한 다음 조회하세요. Windows PowerShell에서는 아래 예시 포트 두 개의 리스닝 프로세스를 확인할 수 있습니다. 조회 결과가 없더라도 해당 시점에 TCP 리스닝을 찾지 못했다는 뜻일 뿐, 권한이나 주소 설정 문제까지 배제할 수는 없습니다.

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

# 이전 단계에서 확인한 프로세스 ID를 -Id에 입력하세요. 4560은 예시입니다
Get-Process -Id 4560

Linux에서는 아래 명령으로 리스닝 주소, 포트 및 프로세스를 확인할 수 있습니다. 다른 사용자의 프로세스 정보를 보려면 추가 권한이 필요할 수 있습니다. 0.0.0.0 또는 ::에서 리스닝 중인 프로세스도 확인하세요. 로컬 주소에 새로 리스닝하려는 프로세스와 충돌할 수 있습니다.

ss -ltnp 'sport = :10808 or sport = :10809'

5. 알 수 없는 프로토콜 및 필드: 코어 지원 여부 확인

JSON 문법이 올바르다는 것은 파일을 파싱할 수 있다는 뜻일 뿐, 필드 조합까지 유효하다는 뜻은 아닙니다. Xray와 V2Fly는 공통된 기반을 갖지만 프로토콜, 전송 방식, 보안 설정을 이름만 보고 서로 바꿔 쓸 수는 없습니다. 특히 REALITY 또는 Xray 전용 흐름 제어 매개변수가 포함된 설정은 해당 기능을 명시적으로 지원하는 코어와 버전에서 사용해야 합니다.

로그 또는 설정 단서우선 확인할 항목해결 방법
unknown config idprotocol에 해당하는 구현이 있는지철자와 대소문자, 코어 지원 여부를 확인하세요. 프로토콜 이름만 바꾸지 마세요.
unknown field필드가 있는 계층과 파서 요구사항실행 중인 버전의 필드 구조와 대조해 클라이언트 설정 필드를 잘못 넣은 것은 아닌지 확인하세요.
streamSettings.security가 reality로 설정됨실행 중인 프로세스가 해당 기능을 지원하는 Xray인지 확인설정에 맞는 코어를 선택하고 전송 및 보안 매개변수 전체를 확인하세요.
라우팅에서 outboundTag 참조이름이 아웃바운드의 tag와 일치하는지태그를 수정하세요. 일부 불일치는 요청을 라우팅할 때에야 드러날 수 있습니다.

알 수 없는 필드가 모두 오류로 표시되는 것은 아닙니다. 일부 파싱 과정에서는 인식하지 못하는 키를 무시합니다. 따라서 “unknown field” 메시지가 없다고 해서 해당 설정이 적용되었다고 볼 수는 없습니다. 구독 그룹이나 자동 업데이트 간격 같은 클라이언트 옵션을 코어 JSON에 임의로 추가하지 말고 클라이언트의 해당 설정에서 관리하세요.

6. geo 파일 누락: 리소스 이름, 경로, 권한 확인

라우팅의 geoip: 및 geosite: 규칙에는 일반적으로 해당 지리 데이터 리소스가 필요합니다. 로그에 failed to load GeoIP 또는 failed to load geosite가 표시되면 오류 체인을 더 확인하세요. 파일을 찾을 수 없는 경우, 읽기에 실패한 경우, 분류 태그를 찾을 수 없는 경우는 서로 다른 문제입니다.

오류: no such file or directory

원인: 오류 체인에 표시된 geo 파일 경로를 확인하세요. 프로세스가 실제 리소스 디렉터리에서 데이터 파일을 찾지 못했을 수 있습니다. 해결: 로그에 표시된 디렉터리를 확인하고 클라이언트의 리소스 업데이트 기능을 사용하거나 프로그램 디렉터리 전체를 복구하세요.

오류: permission denied

원인: 프로세스에 리소스 파일 또는 상위 디렉터리를 읽을 권한이 없을 수 있습니다. 해결: 실행 계정과 디렉터리 권한을 확인하세요. 오류가 로그 파일을 가리킨다면 로그 디렉터리의 쓰기 권한을 확인해야 합니다.

문제 범위를 좁히려면 백업한 복사본에서 geo 데이터 관련 라우팅 규칙을 잠시 제거한 다음 설정 테스트를 실행할 수 있습니다. 복사본이 테스트를 통과해도 원인이 리소스나 규칙으로 좁혀졌다는 뜻일 뿐입니다. 실제 실행 전에 원래 규칙을 수정해야 합니다. 그렇지 않으면 트래픽 분기 방식이 달라집니다.

7. 수정 후 재검사: 설정 통과와 프록시 사용 가능 여부 구분

한 번에 변수 하나만 변경하고 수정 전후의 오류 줄을 기록하세요. 설정 테스트가 성공하면 코어를 실행해 리스닝 여부를 확인하고, 마지막으로 앱 요청이 해당 인바운드에 도달하는지와 예상한 아웃바운드로 라우팅되는지 검증하세요. 웹페이지가 한 번 열렸다고 해서 모든 라우팅 규칙이 올바르다는 뜻은 아닙니다.

설정 테스트는 통과했는데 클라이언트가 계속 시작되지 않는 이유는 무엇인가요?

먼저 두 작업이 같은 파일과 코어를 사용하는지 확인하세요. 다음으로 실행 단계의 포트 바인딩, 로그 쓰기, 실행 권한을 점검합니다. 테스트 명령만으로 포트 사용 가능 여부나 원격 서버 연결 여부를 확인할 수는 없습니다.

config.json을 수정했는데 다시 시작하면 왜 원래대로 돌아가나요?

클라이언트가 임시로 생성한 파일일 수 있습니다. 노드 편집, 라우팅 설정 또는 사용자 지정 설정 원본에서 수정한 뒤 다시 생성하세요. 시작 로그의 실제 파일 경로를 우선하고, 직접 찾은 동명의 파일을 기준으로 판단하지 마세요.

항상 관리자 권한으로 실행해야 하나요?

모든 시작 오류에 관리자 권한 실행을 일괄 적용해서는 안 됩니다. 권한 오류가 파일, 포트, 네트워크 장치 중 무엇을 가리키는지 먼저 확인하세요. 일반적인 로컬 고포트 프록시는 디렉터리와 리스닝 설정을 먼저 점검하고, TUN 등 시스템 기능이 필요한 경우에만 클라이언트 안내에 따라 권한을 부여하세요.

코어는 실행됐는데 웹페이지가 열리지 않으면 어떻게 해야 하나요?

먼저 앱이 올바른 프록시 유형과 포트를 사용하고 있는지 확인하세요. 앱 요청이 실제로 인바운드에 도달한다면 아웃바운드 연결 로그, 노드 매개변수 및 시스템 시간을 점검합니다. 이 단계에서는 연결 문제 해결로 전환하고 모든 문제를 JSON 문법 탓으로 돌리지 마세요.

문제를 제보할 때는 클라이언트 이름, 실제 코어 버전, 시스템 플랫폼, 민감 정보를 삭제한 전체 시작 오류 체인, 문제를 재현할 수 있는 최소 설정 조각을 함께 첨부하세요. 기본 사용법은 빠른 시작 가이드를 참고하세요. 인바운드, 아웃바운드 및 라우팅 필드는 전체 설정 가이드에서 확인할 수 있습니다.

v2rayN 다운로드