v2rayNG를 실행하자마자 중단되거나 설정을 불러오지 못한다는 메시지가 표시되는 경우, 또는 사용자 지정 config를 가져온 뒤 실행되지 않는 경우에 적용할 수 있습니다. 먼저 시작 로그 전체를 보관한 다음 파싱, 필드, 리스닝, 아웃바운드 순서로 확인하세요. 일반 구독 노드는 편집 화면에서 필드를 수정하고, 사용자 지정 설정은 JSON을 직접 확인하면 됩니다. 처음부터 클라이언트를 다시 설치할 필요는 없습니다.
먼저 로그를 열어 시작 오류와 연결 오류 구분하기
v2rayNG 메인 화면 왼쪽 위의 사이드 메뉴를 열고 ‘로그’로 이동하세요. 먼저 서비스를 중지하고 기존 로그를 지운 다음 메인 화면으로 돌아와 문제가 발생한 노드를 선택해 한 번 실행합니다. 이후 다시 ‘로그’를 열어 이번 시작 기록 전체를 보관하세요. 버전에 따라 메뉴 위치가 다를 수 있으니 화면에 표시된 ‘로그’ 항목을 찾으면 됩니다. 마지막 줄의 ‘시작 실패’만 캡처하지 마세요. 실제 원인은 대개 그 위에 표시됩니다.
-
기존 설정 백업
현재 노드 이름과 설정 유형을 기록하세요. 직접 관리하는 JSON은 사본을 저장하고, 구독 노드는 소속 그룹을 적어 두세요. 나중에 업데이트할 때 임시 수정 사항이 덮어쓰이지 않도록 하기 위해서입니다.
-
실행 환경 기록
사이드 메뉴의 ‘정보’에서 클라이언트 버전을 기록하세요. 시작 로그에 Xray 버전이 표시되면 함께 적어 둡니다. 클라이언트 버전과 코어 버전은 서로 다른 번호입니다.
-
한 번만 재현
서비스를 중지하고 로그를 지운 다음 한 번만 실행하세요. Android VPN 권한 요청이 표시되면 먼저 권한을 허용하세요. 권한 취소를 설정 오류로 오인하지 않도록 합니다.
-
오류 원인 따라가기
failed to load config또는failed to start부터 이어서 확인하세요. 원인이 여러 단계로 표시되면 구체적인 필드, 포트 또는 JSON 파싱 오류까지 살펴보세요.
로그가 요청 수신 단계까지 진행된 뒤 connection refused, i/o timeout 또는 인증서 핸드셰이크 오류가 나타난다면 대개 연결 단계의 문제이며, 코어가 시작되지 않은 것은 아닙니다. 이때 JSON 구두점을 계속 바꿔도 원격 포트에 연결할 수 없거나 인증서가 일치하지 않는 문제는 해결되지 않습니다.
앞의 세 단계에서 실패하면 이 글의 설정과 포트를 먼저 확인하세요. 뒤의 두 단계에서 실패하면 라우팅, DNS, 노드 연결 가능 여부와 TLS를 살펴보세요. 로그 문구는 Xray 버전에 따라 달라질 수 있습니다. 아래는 자주 나타나는 오류 문구이며, 로그 한 줄 전체가 똑같을 필요는 없습니다.
첫 번째 유형: JSON 문법 오류, 괄호와 데이터 유형부터 확인
사용자 지정 설정을 붙여 넣은 직후 실행되지 않는다면 먼저 JSON을 확인하세요. 객체의 키와 문자열에는 영문 큰따옴표를 사용해야 하며, 객체나 배열의 마지막 항목 뒤에는 쉼표를 남기지 마세요. 파서별 차이를 줄이려면 문제를 확인하는 동안 주석이 없는 표준 JSON을 사용하세요.
오류: invalid character '}' looking for beginning of object key string
원인: 객체를 닫기 전에 쉼표가 남아 파서가 다음 키를 기다리고 있을 수 있습니다. 해결: 오류 위치 바로 앞의 항목을 확인하고 끝의 쉼표를 삭제하세요. 여는 중괄호와 닫는 중괄호가 올바르게 짝을 이루는지도 확인합니다.
오류: unexpected EOF
원인: 객체, 배열 또는 문자열이 끝나기 전에 내용이 잘렸습니다. 해결: 복사한 범위를 다시 확인해 실제로 빠진 내용을 채우세요. 파일 끝에 괄호만 기계적으로 추가해서는 안 됩니다.
오류: cannot unmarshal string into Go struct field
원인: 필드 유형이 코어에서 기대하는 유형과 다릅니다. 해결: 뒤에 이어지는 필드 경로도 함께 읽고, 해당 필드의 요구사항에 따라 숫자, 불리언, 배열 또는 객체로 수정하세요.
아래는 문법 설명을 위한 일부 객체이며, 그대로 가져올 수 있는 완전한 프록시 설정이 아닙니다. port에는 숫자를, listen에는 문자열을 사용하며 마지막 항목 뒤에는 쉼표를 붙이지 않습니다. 유형 오류가 있으면 필드별로 수정하고, 모든 숫자를 문자열로 바꾸지는 마세요.
{
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks"
}두 번째 유형: 필드명 오타, JSON 문법이 맞아도 설정이 유효한 것은 아닙니다
문법을 확인한 뒤에는 필드 이름, 계층 구조, 열거형 값을 살펴보세요. 최상위에는 보통 단수형이 아닌 inbounds와 outbounds 배열을 사용합니다. 전송 설정은 streamSettings에 지정하고, 그 안의 network 값도 코어에서 지원하는 이름이어야 합니다. 키 이름의 대소문자를 임의로 바꾸지 마세요.
- 계층 오류:
streamSettings를settings안에 넣어도 현재 아웃바운드에 전송 계층을 설정한 것이 아닙니다. - 열거형 오류: WebSocket의 네트워크 값은
ws입니다. 임의로 줄여 쓴websoket을 사용하지 마세요. - 필드 혼용: 공유 링크의 매개변수 이름을 JSON 키 이름으로 그대로 사용하지 마세요. 예를 들어 링크 매개변수와 코어 설정의 TLS 필드 이름은 일대일로 대응하지 않습니다.
- 버전 차이: 새 설정 필드에는 최신 코어가 필요할 수 있습니다. 클라이언트를 업데이트한 뒤에도 실제로 실행 중인 코어 버전을 확인하세요. 다운로드 날짜만으로 판단하면 안 됩니다.
오류: unknown transport protocol: websoket
원인: 전송 프로토콜 이름이 인식 가능한 열거형 값이 아닙니다. 해결: 서버 요구사항에 맞게 streamSettings.network를 수정하세요. 서버가 WebSocket을 사용한다면 ws를 입력해야 합니다.
일부 알 수 없는 필드는 오류를 표시하는 대신 파서에서 무시될 수 있다는 점도 유의하세요. 따라서 ‘문법 오류가 없다’고 해서 매개변수가 적용됐다는 뜻은 아닙니다. 일반 노드는 메인 화면으로 돌아가 해당 노드의 편집 화면을 열고 주소, 포트, 프로토콜, 전송 설정을 하나씩 대조하세요. 필드 하나를 수정하려고 노드 전체를 사용자 지정 JSON으로 바꾸지 마세요.
세 번째 유형: inbound 리스닝 충돌, 주소와 포트 확인
로그에 bind: address already in use가 표시되면 로컬 리스닝 엔드포인트가 이미 사용 중이라는 뜻입니다. 이는 기기의 포트 충돌이지 노드 서버가 연결을 거부한 것이 아닙니다. 먼저 다른 프록시 서비스를 중지한 다음 사용자 지정 설정에 동일한 리스닝 주소, 포트, 전송 프로토콜이 중복으로 지정되어 있는지 확인하세요.
이 숫자는 문제 해결 방법을 설명하기 위한 예시이며 모든 버전의 기본값은 아닙니다. 일반 설정은 사이드 메뉴의 ‘설정’에서 로컬 SOCKS 포트 항목을 찾아 변경한 뒤 서비스를 중지하고 다시 시작하세요. 항목 이름은 버전에 따라 다를 수 있습니다. 사용자 지정 JSON에서는 실제 inbounds의 listen과 port를 확인하세요. 일반 설정이 사용자 지정 설정을 덮어쓴다고 가정하지 마세요.
오류: listen tcp 127.0.0.1:10808: bind: address already in use
원인: 해당 TCP 리스닝 엔드포인트를 다른 리스너가 이미 사용하고 있습니다. 해결: 해당 서비스를 중지하거나 사용 중이 아닌 높은 번호의 포트를 선택하세요. 이후 프록시 포트를 수동으로 입력한 앱도 함께 수정해야 합니다.
요점: 로컬 포트만 변경하고 노드 포트는 변경하지 마세요
로그에 listen과 bind가 보이면 먼저 로컬 인바운드 문제를 해결하세요. 원격 서버 포트까지 10818로 바꾸지 마세요. 원격 포트는 서버에서 실제로 리스닝 중인 포트와 일치해야 합니다.
0.0.0.0은 모든 인터페이스에서 리스닝한다는 뜻이므로 동일한 포트의 특정 IPv4 주소 리스너와 충돌할 수 있습니다. 두 인바운드의 충돌 여부는 TCP, UDP, 주소 계열에도 영향을 받으므로 포트 번호만으로 판단할 수 없습니다. 문제를 피하려고 LAN 접근을 무작정 허용하지 마세요. 로컬 프록시에 접근할 수 있는 범위가 넓어집니다.
네 번째 유형: outbound 매개변수 누락, 프로토콜별 필수 항목 확인
아웃바운드는 연결할 서버, 사용할 프로토콜, 인증 방식을 결정합니다. 일반적인 VMess와 VLESS JSON 아웃바운드는 settings.vnext에 서버를, users에 사용자를 정의합니다. Trojan은 보통 settings.servers를 사용합니다. 서로 다른 프로토콜의 필드를 섞으면 JSON 문법이 올바르더라도 아웃바운드를 구성하는 단계에서 실패할 수 있습니다.
| 프로토콜 | 먼저 확인할 설정 경로 | 자주 발생하는 문제 |
|---|---|---|
| VMess | settings.vnext[].address / port / users[].id | 주소 누락, 포트 누락, 사용자 ID 형식 오류 |
| VLESS | settings.vnext[].users[].id / encryption | UUID 형식이 올바르지 않음. 일반 설정의 encryption은 none이어야 하며 현재 코어의 요구사항도 충족해야 함 |
| Trojan | settings.servers[].address / port / password | vnext 구조를 잘못 사용했거나 비밀번호 또는 서버 주소가 누락됨 |
오류: invalid UUID
원인: 사용자 ID를 해당 코어가 허용하는 형식으로 파싱할 수 없습니다. 해결: 원본 노드 정보에서 ID 전체를 다시 복사하고 공백, 잘림, 전각 문자가 있는지 확인하세요. 서버 계정 대신 새 ID를 임의로 만들지 마세요.
오류: failed to build outbound handler
원인: 아웃바운드 구성 실패를 알리는 상위 오류이며, 이 문구만으로 어떤 매개변수가 누락됐는지는 알 수 없습니다. 해결: 중첩된 원인 메시지까지 확인하고 해당 프로토콜에 따라 서버 목록, 사용자 매개변수, 전송 계층 설정을 점검하세요.
연결 주소, TLS 서버 이름, WebSocket Host는 서로 다른 용도의 필드입니다. 모두 도메인처럼 보여도 서로 바꿔 쓸 수 없습니다. VLESS와 REALITY를 함께 사용할 때는 서버와 일치하는 공개 키, 서버 이름 및 관련 매개변수도 확인해야 합니다. 필드 이름과 지원 여부는 실제 코어 버전을 기준으로 확인하세요. 매개변수가 누락됐다면 다른 노드의 값을 복사하지 말고 설정 제공자에게 문의하세요.
수정 후 다시 시작하고 되돌릴 수 있도록 문제 해결 기록 보관
한 번에 한 유형만 수정한 다음 서비스를 중지하고 다시 시작해 새 로그를 확인하세요. 먼저 문법을 해결하고 필드와 매개변수를 점검한 뒤 리스닝이 정상인지 확인합니다. 포트, DNS, 프로토콜, 라우팅을 한꺼번에 바꾸면 연결이 복구되더라도 어떤 수정이 효과가 있었는지 알기 어렵습니다.
- 일반 구독 노드: 먼저 구독 그룹 메뉴에서 업데이트를 실행한 뒤 가져온 결과를 확인하세요. 노드 하나만 실패했다면 해당 노드의 로그를 보관하고 그룹 전체를 삭제하지 마세요.
- 사용자 지정 설정: 수정 전후 사본을 보관하고 변경한 필드와 시간을 기록하세요. 유일하게 사용할 수 있는 설정 파일을 바로 덮어쓰지 마세요.
- 정상 작동이 확인된 노드: 같은 기기에서 비교해 보세요. 해당 노드가 시작된다면 모든 설정을 바로 초기화하지 말고 문제가 발생한 노드부터 점검하세요.
- 계속 시작되지 않는 경우: 클라이언트와 코어 버전, 민감 정보를 가린 전체 오류 원인, 설정 출처 유형, 최근 변경 사항을 제공하세요. ‘연결할 수 없음’ 화면만으로는 config 오류를 찾기 어렵습니다.
코어는 시작됐지만 Android VPN이 연결되지 않는다면 시스템 권한과 VPN을 사용 중인 다른 앱을 확인하세요. Android에서는 일반적으로 동일 사용자 환경에서 활성 VPN 하나만 유지할 수 있습니다. 이런 문제는 시스템 VPN 상태를 기준으로 해결하면 되며 UUID를 계속 바꾸거나 인증서 검증을 끌 필요는 없습니다.