Clash 구독 링크 파싱 오류 해결: 자주 발생하는 원인과 점검 방법

먼저 구분하세요: 다운로드 실패, 파싱 실패, 설정 로드 실패

Clash 클라이언트에 ‘구독 실패’가 표시되어도 구독 링크가 만료된 것은 아닐 수 있습니다. 구독을 가져올 때는 보통 링크 요청, 응답 수신, 설정 파싱, 코어 로드 단계를 거칩니다. 어느 단계에서 오류가 발생했는지에 따라 네트워크, 텍스트 형식, 코어 호환성 중 무엇을 확인할지 달라집니다.

사용 중인 설정을 먼저 보존하세요. 기존 구독을 삭제하거나 유일한 로컬 백업을 덮어쓰지 마세요. 업데이트에 실패해도 기존 설정은 계속 정상 작동할 수 있습니다.
오류 정보를 빠짐없이 기록하세요. 클라이언트 로그나 가져오기 안내에서 실패 시각, HTTP 상태 코드, 오류 필드, 행 번호를 확인하세요. ‘실패’라는 문구만 캡처해서는 원인을 찾기 어렵습니다.
클라이언트와 코어를 확인하세요. 클라이언트 이름과 버전, 코어가 Clash Meta(현 mihomo)인지 기록하세요. 인터페이스 버전과 코어 버전은 서로 다른 정보입니다.
한 번에 하나씩 변경하세요. 먼저 링크와 응답을 확인하고, 다음으로 YAML을 점검한 뒤 프록시 그룹과 규칙을 살펴보세요. 변경할 때마다 직접 업데이트해 여러 설정을 동시에 바꾸지 않도록 합니다.

오류 메시지에 따라 점검 순서를 정하세요

클라이언트마다 오류 문구는 다를 수 있지만, 실제 오류는 대체로 아래 항목에 해당합니다. 상태 코드는 서버의 응답 방식만 나타내며 계정 잔액, 구독 기간, 기기 수를 단독으로 확정해 주지는 않습니다.

오류 또는 증상	먼저 확인할 사항	다음 단계
`401`、`403`	인증 실패, 접근 제한 또는 보안 차단	구독 링크를 다시 복사하고 계정 상태와 서비스 제공자 안내를 확인하세요
`404`、`410`	주소 만료, 경로 변경 또는 리소스 삭제	관리 페이지에서 현재 주소를 확인하고 기존 즐겨찾기는 사용하지 마세요
`429`	요청이 너무 많음	연속으로 새로고침하지 말고 서버 안내에 따라 기다린 뒤 다시 시도하세요
`timeout`、`no such host`	연결 시간 초과 또는 도메인 확인 실패	네트워크를 바꿔 직접 연결과 프록시 업데이트 결과를 비교하세요
`x509` 또는 인증서 오류	시스템 시간, 인증서 체인 또는 HTTPS 연결 차단 문제	시간을 맞추고 네트워크 인증 및 인증서 환경을 확인하세요
`yaml: line …`	텍스트 구문 오류 또는 설정이 아닌 응답	응답 내용과 해당 행 주변의 문맥을 확인하세요
`unsupported proxy type`	코어에서 노드 프로토콜이나 필드 조합을 지원하지 않음	설정 요구 사항과 실제 사용 중인 코어를 대조하세요
프록시 그룹이나 규칙에서 존재하지 않는 항목을 참조함	이름 불일치, 노드 필터링 또는 설정 누락	참조 관계를 따라 노드, 프록시 그룹, 규칙을 확인하세요

구독 링크 확인: 주소 전체를 복사한 뒤 계정 상태를 점검하세요

복사 오류와 잘못된 주소 선택을 확인하세요

서비스 제공자 관리 페이지에서 구독 주소의 복사 버튼을 사용하세요. 링크가 https://로 시작하는지, 끝에 줄바꿈, 공백 또는 한국어 문장 부호가 붙지 않았는지 확인하세요. 물음표 뒤의 매개변수를 직접 삭제하거나 메신저에 생략되어 표시된 텍스트를 전체 주소로 착각하지 마세요.

관리 페이지와 구독 API를 구분하세요: 계정 페이지가 열린다고 해서 클라이언트에서 읽을 설정 주소를 받은 것은 아닙니다.
단일 노드와 구독을 구분하세요: ss://, vmess:// 등은 노드 공유 URI일 수 있으며, 바로 업데이트할 수 있는 완전한 Clash 설정이 아닙니다.
링크가 재설정되었는지 확인하세요: 비밀번호 변경, 구독 토큰 재설정, 서비스 이전 후에는 기존 링크가 작동하지 않을 수 있습니다.
서비스 상태를 확인하세요: 관리 페이지에서 구독 만료, 트래픽 소진, 서비스 일시 중지 여부를 확인하세요. 클라이언트 오류만으로 상태를 추측하지 마세요.

브라우저에서는 열리는데 클라이언트에서는 왜 실패하나요?

브라우저에는 로그인 쿠키가 남아 있거나 웹 페이지 인증이 자동으로 처리될 수 있지만, 클라이언트 요청에는 같은 로그인 상태가 적용되지 않는 경우가 많습니다. 브라우저에 ‘접속 성공’이라고 표시되어도 실제 응답은 로그인 페이지, 인증 화면 또는 구독 안내 페이지일 수 있습니다. 페이지가 열리는지만 보지 말고 응답이 설정 텍스트인지 확인하세요.

상태 코드가 200이어도 응답이 <!DOCTYPE html>로 시작하거나 오류 설명이 담긴 JSON일 수 있습니다. 이때 YAML 오류는 뒤따라 나타난 증상일 뿐이며, 실제로는 API 접근이나 계정 인증을 해결해야 합니다.

구독 형식 확인: Clash 설정과 노드 목록은 다릅니다

완전한 Clash 설정은 보통 YAML 매핑 형식이며, 최상위 필드로 proxies, proxy-groups, rules 등이 포함될 수 있습니다. 일부 구독은 Base64로 인코딩된 노드 목록이나 다른 클라이언트 전용 설정을 반환합니다. 모두 ‘구독’이라고 부를 수는 있지만 가져오는 방법까지 같다고 볼 수는 없습니다.

완전한 설정, 노드 제공자, 단일 노드의 차이

완전한 설정: 보통 클라이언트의 설정 또는 구독 관리 메뉴에서 가져오며, 프록시 그룹과 규칙 등 실행에 필요한 설정을 제공합니다.
노드 제공자 파일: proxy-providers에서 참조하는 파일로, 일반적으로 proxies 목록이 중심이며 완성된 사용 설정과는 다릅니다.
단일 노드 URI 또는 인코딩된 목록: 해당 가져오기 방식을 클라이언트가 명시적으로 지원해야 합니다. 지원하지 않는다면 서비스 제공자에게 호환되는 Clash 또는 mihomo 형식을 요청하세요.

현재 클라이언트나 코어에 맞는다고 서비스 제공자가 명시한 주소를 우선 사용하세요. 일부 서비스는 요청의 User-Agent에 따라 형식을 다르게 반환하므로 같은 주소라도 브라우저와 클라이언트의 응답이 다를 수 있습니다. 임의로 요청 헤더를 위조해 시도하지 말고 서비스 제공자의 연결 안내부터 확인하세요.

YAML 확인: 오류 행부터 보고 바로 윗행도 점검하세요

응답이 실제 설정인지 확인한 뒤 YAML을 점검하세요. 설정을 로컬에 저장하고 행 번호, 공백, 탭을 확인할 수 있는 편집기로 여세요. 파서가 표시한 행은 ‘더 이상 파싱할 수 없다고 판단한 위치’입니다. 실제 오류는 바로 윗행의 따옴표, 콜론 또는 들여쓰기에 있을 수 있습니다.

자주 발생하는 구문 오류와 올바른 작성법

들여쓰기에는 공백을 사용하세요. 각 단계에 공백 2칸을 사용하는 것이 좋으며, 계층 구분에 Tab을 사용하지 마세요. 같은 수준의 필드는 줄을 맞춰야 합니다.
콜론 뒤에 공백을 넣으세요. mixed-port: 7890은 키와 값의 올바른 표기입니다. mixed-port:7890은 같은 매핑 구조로 해석되지 않습니다.
영문 문장 부호를 사용하세요. 전각 콜론, 곡선 따옴표, 전각 공백은 구문을 바꿀 수 있으므로 서식 편집기로 설정을 수정하지 마세요.
목록의 하이픈을 확인하세요. rules 같은 목록의 각 항목 앞에는 - 가 필요합니다. 하이픈 뒤 공백을 빠뜨리지 마세요.
최상위 키를 중복해서 추가하지 마세요. 같은 이름의 dns나 rules 블록을 두 번 만들지 마세요. 파서마다 중복 키를 처리하는 방식이 다를 수 있습니다.

아래는 기본 필드의 구문 예시일 뿐, 원격 노드를 포함하지 않으며 구독을 대신하지도 않습니다. 포트, 모드, 중첩 필드, 규칙 목록의 계층 구조를 보여 줍니다.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

dns:
  enable: true
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,DIRECT

여기서 7890은 예시 수신 포트이며 구독 다운로드 포트가 아닙니다. 이 값을 바꿔도 원격 구독 파싱 오류가 해결되는 경우는 드뭅니다. 예시의 DNS 주소도 모든 네트워크에서 접속된다고 보장할 수 없습니다. 실제 설정은 네트워크 환경에 맞춰 선택하고, 들여쓰기 오류를 고치려고 기존 DNS 설정을 통째로 덮어쓰지 마세요.

구문 오류를 해결한 뒤에는 이름 참조도 확인하세요

YAML을 읽을 수 있다고 해서 코어가 설정을 반드시 로드하는 것은 아닙니다. 규칙이 MATCH,Proxy로 지정되어 있다면 설정에 프록시 그룹처럼 유효한 Proxy라는 아웃바운드 대상이 있어야 합니다. 그룹 이름의 대소문자, 공백, 기호를 정확히 일치시키세요. 노드 필터 조건이 후보 노드를 모두 제외했다면 프록시 그룹에서 선택할 대상이 남아 있는지도 확인해야 합니다.

구독으로 생성된 파일을 로컬에서 수정하면 다음 업데이트 때 변경 내용이 덮어써질 수 있습니다. 오래 유지할 설정은 클라이언트가 지원하는 오버라이드, 병합 또는 확장 설정 기능을 사용하고, 적용 범위를 먼저 확인하세요.

네트워크 점검: 구독 다운로드와 노드 연결을 따로 테스트하세요

노드에 연결할 수 있어도 구독 도메인에 접속할 수 있다는 뜻은 아닙니다. 구독을 다운로드해도 모든 노드가 작동한다는 보장은 없습니다. 로그에 시간 초과, 도메인 확인 또는 TLS 오류가 나타나면 먼저 요청 경로를 해결하고 노드 프로토콜이나 분할 라우팅 규칙은 바로 수정하지 마세요.

일반 웹사이트에 접속되는지 확인하세요. 공용 Wi-Fi는 브라우저에서 먼저 인증해야 할 수 있습니다. 시스템 날짜나 시간대가 잘못되어도 HTTPS 인증서 검증이 실패할 수 있습니다.
네트워크를 바꿔 비교하세요. 예를 들어 집에서 쓰는 인터넷 대신 휴대전화 핫스팟으로 바꾸고 같은 클라이언트에서 수동 업데이트를 한 번 실행하세요. 다른 설정은 그대로 두고 네트워크만 바꾸면 현재 네트워크의 제한 여부를 확인하기 쉽습니다.
직접 연결 업데이트와 프록시 업데이트를 구분하세요. 클라이언트에서 구독 업데이트 연결 방식을 선택할 수 있다면 두 방식을 각각 테스트하세요. 일부 클라이언트의 업데이트 요청은 시스템 프록시를 따르지 않으므로 시스템 프록시 설정만 보고 실제 연결 경로를 판단할 수 없습니다.
작동하지 않는 로컬 프록시를 확인하세요. Windows 11에서는 「설정」→「네트워크 및 인터넷」→「프록시」에서 수동 프록시 주소를 확인할 수 있습니다. 종료된 127.0.0.1:7890을 계속 가리킨다면 해당 설정을 따르는 요청이 실패할 수 있습니다. 실제 포트는 클라이언트 설정을 기준으로 확인하세요.
업데이트가 막히는 상황을 만들지 마세요. 기존 프록시를 통해서만 구독을 다운로드할 수 있다면 업데이트 전에 작동하는 설정을 따로 보관하세요. 기존 설정을 삭제하면 구독 요청에 사용할 연결 경로까지 사라질 수 있습니다.

429 오류가 발생하면 업데이트 버튼을 반복해서 누르지 마세요. 서버에서 Retry-After를 제공하면 안내된 시간만큼 기다리세요. 5xx 오류가 발생하면 시각과 상태 코드를 기록한 뒤 서비스 제공자에게 문의하세요. 계속 새로고침해도 서버 오류는 해결되지 않으며 추가 제한이 걸릴 수 있습니다.

가져온 뒤 확인할 사항과 문의 시 준비할 정보

가져오기에 성공했다는 것은 설정이 받아들여졌다는 뜻일 뿐, 트래픽이 해당 설정으로 처리된다는 뜻은 아닙니다. 현재 선택된 설정을 확인하고 프록시 그룹, 규칙 모드, 시스템 프록시 또는 TUN 상태를 점검하세요. TUN은 트래픽을 처리하기 위한 기능이지 구독 텍스트 형식을 수정하는 옵션이 아닙니다.

세 단계로 결과를 확인하세요

설정 단계: 업데이트 시각이 바뀌었는지, 노드와 프록시 그룹이 정상적으로 표시되는지, 로그에 구문 또는 참조 오류가 더는 없는지 확인하세요.
연결 단계: 노드 하나를 선택해 연결을 테스트하세요. 지연 시간 테스트 실패와 구독 파싱 실패는 서로 다른 단계에서 발생하므로 따로 기록해야 합니다.
트래픽 단계: 프록시를 사용해야 하는 사이트에 접속한 뒤 연결 기록에서 적용된 규칙과 실제 아웃바운드를 확인하세요. 규칙 모드에서 일부 요청이 직접 연결되는 것은 정상적인 설정일 수 있습니다.

계속 실패한다면 다음 정보를 준비하세요

서비스 제공자나 클라이언트 유지관리자에게 문의할 때 클라이언트 버전, 코어 버전, 운영체제 버전, 실패 시각, HTTP 상태 코드, 민감 정보를 가린 전체 오류 내용을 함께 전달하세요. YAML 행 번호가 표시되면 해당 행과 앞뒤 3행을 민감 정보가 보이지 않게 첨부하세요. 네트워크 문제라면 직접 연결, 프록시, 휴대전화 핫스팟 테스트 결과도 각각 알려 주세요.

‘Clash가 안 돼요’라고만 보내거나 구독 파일 전체를 공개하지 마세요. ‘요청 실패’, ‘파싱 실패’, ‘로드 실패’, ‘연결 실패’를 구분하면 불필요한 추가 확인을 줄일 수 있습니다. 트래픽 처리 설정을 확인하려면 시스템 프록시 입문 단계를 참고하세요. 설정 필드와 인터넷 연결 문제는 문제 해결 안내서의 config.yaml 항목에서 이어서 확인할 수 있습니다.