Clash 구독 가져오기 실패·파싱 오류 해결 방법: 원인별 점검 절차

구독 다운로드 실패와 설정 불러오기 실패 구분하기

‘구독 가져오기 실패’는 여러 단계에서 발생할 수 있습니다. 클라이언트가 응답을 받지 못했거나, 서버가 오류 페이지를 반환했거나, 설정 파일을 파싱하지 못했거나, 현재 커널이 설정에 포함된 프로토콜을 지원하지 않는 경우입니다. 이 가운데 커널 호환성을 집중적으로 확인해야 하는 경우는 마지막뿐입니다. 노드를 계속 바꿔도 앞의 세 가지 문제는 대개 해결되지 않습니다.

FlClash는 mihomo 커널을 사용합니다. 클라이언트는 구독 관리와 화면 표시, 설정 처리를 담당하고 커널은 설정 검증과 트래픽 전달을 담당합니다. 화면에 ‘업데이트 실패’가 표시되면 해당 업데이트의 오류 상세 정보와 이후 커널 로딩 오류가 발생했는지를 함께 확인하세요. 버전에 따라 메뉴 이름은 달라질 수 있으므로, 아래에서는 기능을 기준으로 설명합니다. 특정 버전의 메뉴 경로를 모든 플랫폼에 공통으로 적용하지 마세요.

오류 단서	우선 확인할 항목	다음 단계
`timeout`、`no such host`	링크 접속 및 도메인 조회	다운로드 요청을 테스트하고 요청에 사용된 네트워크 경로 확인
HTTP `401`、`403`、`404`	접근 권한, 접속 제한 또는 주소 변경	서비스 제공업체 계정에서 구독 상태와 최신 주소 확인
`yaml:`、`unmarshal`	응답 내용과 YAML 데이터 형식	먼저 HTML이 아닌지 확인한 뒤 오류 행과 앞부분 점검
`unsupported proxy type`	노드 프로토콜 및 커널 지원 범위	실행 중인 커널 버전과 노드 필드 확인
`proxy … not found`	그룹 설정 및 노드 참조	이름, 필터 조건, 오버라이드가 적용된 최종 설정 확인

점검 전에 세 가지 정보 보관하기

FlClash 버전, 운영체제, 실제 커널 버전을 기록하세요. 커널 업데이트와 클라이언트 업데이트는 함께 이루어지지 않을 수 있으므로 ‘최신 버전’이라고만 적지 마세요.
실패 시각 전후의 로그를 보관하세요. 예를 들어 업데이트를 실행하기 전후로 각각 30초간의 로그를 확인해 다운로드, 파싱, 로딩 단계를 구분합니다.
정상 작동 중인 설정은 백업하세요. 테스트용 설정을 새로 만들어 가져오고, 유일하게 사용할 수 있는 설정 파일을 바로 덮어쓰지 마세요.

구독 URL에는 접근 토큰이 포함되는 경우가 많습니다. 스크린샷, 로그, 설정 파일을 공유하기 전에 URL 쿼리 매개변수의 인증 정보와 노드 비밀번호, UUID, 인증 헤더, 개인 경로를 삭제하세요. 도메인만 가려서는 구독 권한을 보호할 수 없습니다.

1단계: 링크 접속 및 HTTP 상태 확인

먼저 주소를 확인한 뒤 네트워크 점검하기

서비스 제공업체 계정 페이지에서 Clash 또는 mihomo용 구독 주소를 다시 복사하세요. 주소가 https://로 시작하는지, 끝에 공백이나 줄바꿈, 따옴표, 한글 문장 부호가 붙지 않았는지 확인합니다. 계정 로그인 페이지, 요금제 상세 페이지, QR 코드 이미지 주소는 설정 구독 주소가 아닙니다. QR 코드는 이미지를 클라이언트에 가져오는 대신 실제 링크로 디코딩해야 합니다.

브라우저에서 링크가 열린다고 해서 브라우저가 보낸 요청만 성공했다는 뜻입니다. 브라우저에는 로그인 쿠키가 포함될 수 있고, 클라이언트와 다른 프록시 경로를 사용할 수도 있습니다. 구독 백그라운드 작업은 브라우저 로그인 상태를 이어받지 않는 경우가 많습니다. 따라서 클라이언트 업데이트와 별도 다운로드를 각각 테스트하고, 두 요청이 같은 네트워크 경로를 사용한다고 가정하지 마세요.

제한된 다운로드로 응답 확인하기

macOS 또는 Linux의 Bash 터미널에서는 다음 명령을 사용할 수 있습니다. 주소는 숨김 입력으로 받아 명령 기록에 남지 않도록 합니다. 구독 내용을 터미널에 출력하지 않고 현재 디렉터리에 저장하므로, 본인만 접근할 수 있는 임시 작업 디렉터리에서 실행하세요.

read -r -s -p '구독 주소 입력: ' SUB_URL
printf '\n'
curl --location --max-redirs 3 \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 10 --max-time 30 \
  --output subscription-response.txt \
  --write-out 'HTTP %{http_code}\n유형 %{content_type}\n바이트 %{size_download}\n' \
  "$SUB_URL"
unset SUB_URL

이 명령은 연결 제한 시간을 10초, 전체 제한 시간을 30초로 설정하고 리디렉션을 최대 3회 따라가며 HTTPS만 허용합니다. 이는 이번 진단을 위한 매개변수이지 FlClash 기본 설정이 아닙니다. Windows PowerShell에서는 curl.exe에 같은 이름의 매개변수를 사용할 수 있습니다. Bash의 read와 줄 연결 표기법은 그대로 복사하지 마세요.

HTTP 200: 정상 상태 응답을 받았다는 뜻이지만, 본문도 확인해야 합니다. 로그인 페이지나 오류 안내 페이지도 200을 반환할 수 있습니다.
HTTP 301/302: 리디렉션된 주소가 예상한 서비스에 속하는지 확인하세요. 토큰이 포함된 전체 리디렉션 주소를 공개적으로 붙여 넣지 마세요.
HTTP 401/403: 토큰이 재설정되었는지, 요금제가 유효한지, 계정에 접근 제한이 있는지 확인하세요. 403은 보안 보호 서비스에서 반환할 수도 있습니다.
HTTP 404/410: 먼저 링크가 만료되었거나 API가 이전되었는지 확인하세요. 임의로 경로를 바꿔 복구를 시도하지 마세요.
HTTP 429: 연속으로 새로고침하지 말고 서버 안내에 따라 기다리세요. 자동 재시도를 반복하면 요청 제한 시간이 길어질 수 있습니다.
HTTP 5xx: 발생 시각과 상태 코드를 기록하고 잠시 후 다시 시도한 다음 서비스 제공업체에 문의하세요. 로컬 YAML을 수정해도 서버 오류는 해결되지 않습니다.

결과가 HTTP 000이라면 보고할 수 있는 HTTP 상태를 받지 못했다는 뜻이며, 서버가 실제로 ‘000’을 반환한 것은 아닙니다. curl 오류 메시지와 함께 DNS, 연결 시간 초과, TLS 인증서를 확인하세요. 인증서 오류가 발생하면 먼저 기기 시간과 인증서 유효 기간, 네트워크 차단 여부를 확인해야 합니다. 인증서 검증을 꺼서 장기간 우회하지 마세요.

구독 업데이트의 의존성 꼬임 방지하기

구독 도메인에 접속하려면 프록시가 필요하지만 사용할 수 있는 설정이 없다면 최초 업데이트가 완료되지 않을 수 있습니다. 반대로 프록시 출구가 구독 서비스에서 차단된다면 직접 연결이 더 적합할 수 있습니다. 클라이언트에 구독 업데이트용 프록시 설정이나 다운로드 정책이 있는지 확인하고, 한 번에 경로 하나만 변경해 결과를 기록하세요. TUN 모드는 파싱 오류를 해결하는 기능이 아닙니다. TUN, DNS, 구독 주소를 동시에 바꾸지 마세요.

2단계: 응답이 웹 페이지나 다른 구독 형식이 아닌 설정 파일인지 확인

로컬 텍스트 편집기에서 subscription-response.txt를 열어 본인 기기에서만 확인하세요. Content-Type은 참고 정보로 볼 수 있지만, 서버가 일괄적으로 text/plain이나 다운로드용 형식을 사용할 수 있으므로 응답 헤더만 보고 내용이 유효하다고 판단해서는 안 됩니다.

본문 특징	가능한 의미	대처 방법
`<!DOCTYPE html>`、`<html>`	로그인 페이지, 보안 확인 페이지 또는 오류 웹페이지	직접 구독 주소를 새로 발급받고, 보안 확인은 서비스 제공업체에 문의하세요.
`{"error":` 등의 JSON 내용	API 오류 또는 설정용이 아닌 API	오류 필드를 확인하고 권한 및 계정 상태를 점검하세요.
`ss://`, `vmess://` 등 한 줄씩 나열된 URI	노드 링크 모음	클라이언트가 해당 가져오기 형식을 지원하는지 확인하고, 가능하면 Clash/mihomo 형식을 선택하세요.
연속된 Base64 텍스트	인코딩된 노드 목록일 수 있습니다.	구독 형식을 확인하고 YAML로 바로 불러오지 마세요.
`proxies:`、`proxy-groups:`	Clash 설정일 수 있습니다.	들여쓰기, 필드 유형, 참조 관계를 계속 점검하세요.

전체 설정 파일과 노드 공급자 파일도 서로 다릅니다. proxies:만 포함된 파일은 proxy-providers에 사용할 수 있지만, 클라이언트에 필요한 그룹 설정과 규칙이 들어 있지 않을 수 있습니다. payload:만 포함된 파일은 보통 규칙 세트이지 노드 구독이 아닙니다. 실제 가져오기 동작은 클라이언트가 템플릿을 보완하는지에 따라 달라집니다. YAML로 읽을 수 있다는 사실만으로 완전한 설정으로 실행할 수 있는 것은 아닙니다.

일부 서비스는 요청의 User-Agent에 따라 서로 다른 형식을 반환합니다. 같은 주소가 브라우저와 클라이언트에서 다른 내용을 반환한다면 서비스 제공업체에 올바른 접속 주소와 대상 형식을 확인하세요. 요청 헤더를 무작정 위조하지 마세요. 형식 변환이 필요하면 서비스 제공업체가 제공하거나 직접 관리할 수 있는 변환 도구를 우선 사용하세요. 전체 구독 내용을 공개 변환 사이트에 맡기면 구독 인증 정보도 함께 넘기는 셈입니다.

3단계: YAML 문법, 필드 유형, 이름 참조 확인

오류 줄은 문제가 발견된 위치일 뿐, 원인 위치와 다를 수 있습니다.

yaml: line 12는 파서가 12행 근처에서 오류를 발견했다는 뜻입니다. 실제 원인은 따옴표가 닫히지 않았거나 상위 항목의 들여쓰기가 달라진 것처럼 바로 앞 행에 있을 수 있습니다. 오류 행 앞뒤 5행부터 확인하고 노드 목록 전체를 바로 삭제하지 마세요.

들여쓰기에는 공백을 사용하고 Tab은 사용하지 마세요. 같은 깊이의 항목은 일정한 간격을 유지합니다. 예를 들어 각 단계에 공백 2개를 사용하세요.
매핑 필드에는 반각 콜론을 사용하고, 콜론 뒤에는 보통 공백을 둡니다. 예: mode: rule.
목록 항목에는 반각 -를 사용하고, 해당 필드 아래에 있는지 확인하세요.
: , # 또는 복잡한 기호가 포함된 이름, 비밀번호, URL은 적절한 따옴표로 감싸세요. 따옴표 안에서도 해당 이스케이프 규칙을 따라야 합니다.
포트 필드는 정수여야 하며, proxies는 목록이어야 합니다. 문법이 올바르더라도 유형이 잘못되면 설정을 디코딩하는 과정에서 실패합니다.

최소 설정으로 문법 오류 분리하기

다음은 문제를 분리하기 위한 최소 직접 연결 설정으로, 프록시 노드는 포함하지 않습니다. 혼합 포트는 17890으로 지정했으며 예시용 값입니다. 사용 전에 다른 프로세스가 점유하지 않았는지 확인하세요. 이 설정은 프록시 노드를 통한 아웃바운드 연결을 제공하지 않습니다.

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

proxies: []

proxy-groups:
  - name: "진단 출구"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,진단 출구

최소 설정은 검증되지만 원래 구독은 검증되지 않는다면 원본 파일과 설정 병합 과정이 점검 대상입니다. 포트 사용 중 또는 권한 오류가 계속 발생하면 실행 환경 문제로 넘어간 것이므로 YAML 문법 오류로 계속 다루면 안 됩니다. 또한 이 설정의 직접 연결 동작만으로 프록시 노드가 정상이라고 판단할 수 없습니다.

로컬에 mihomo 실행 파일이 있다면 터미널에서 mihomo -t -f ./subscription-response.txt를 실행해 설정을 확인할 수 있습니다. 이 명령은 현재 터미널에서 찾은 커널을 사용하므로 FlClash 내장 버전과 다를 수 있습니다. 일부 공급자 설정은 외부 리소스를 검사할 수도 있으니 제어 가능한 로컬 환경에서 테스트하세요. 검사를 통과해도 모든 노드의 연결이 보장되지는 않습니다.

그룹 설정, 규칙, 오버라이드 적용 후 최종 내용 확인하기

오류가 프록시 이름을 찾을 수 없다고 표시되면 노드 이름과 그룹 설정의 참조를 공백과 대소문자까지 포함해 정확히 비교하세요. 규칙의 마지막 아웃바운드 이름은 실제로 존재하는 노드, 그룹 설정 또는 내장 아웃바운드를 가리켜야 합니다. use로 참조하는 이름은 proxy-providers의 키와 일치해야 합니다. 공급자 이름을 일반 노드 참조 대신 사용할 수는 없습니다.

구독 원본은 검증되지만 클라이언트에서 불러오지 못한다면 클라이언트의 오버라이드, 설정 병합, 노드 필터 조건을 확인하세요. 필터 표현식이 후보 노드를 모두 삭제했거나 이름 변경 후 이전 참조가 남아 있을 수 있습니다. 먼저 테스트 설정에서 사용자 지정 처리를 끈 다음 항목별로 다시 활성화하세요. 구독 캐시를 직접 수정해도 다음 업데이트 때 덮어써질 수 있습니다.

4단계: 노드 프로토콜과 실제 실행 중인 커널 확인

Clash 설정 형식이라고 해서 모든 Clash 계열 클라이언트가 같은 프로토콜을 지원하는 것은 아닙니다. 기존 Clash와 mihomo, 그리고 세대가 다른 커널 버전은 지원하는 프로토콜과 필드가 다를 수 있습니다. unsupported proxy type 오류가 발생하면 먼저 오류에 표시된 type 값을 기록한 다음 커널 버전과 릴리스 정보를 확인하세요.

프로토콜 이름을 확인하세요. 노드가 type: hysteria2로 설정되어 있다면 해당 프로토콜을 지원하는 커널이 필요합니다. 유형을 ss로 바꿔서 작동하게 만들 수는 없습니다.
필수 항목과 데이터 유형을 확인하세요. server, port, 비밀번호 또는 UUID 등의 필드를 점검하세요. 필수 항목은 프로토콜에 따라 다릅니다.
전송 및 TLS 매개변수를 확인하세요. 연결 주소, SNI, WebSocket 경로 및 관련 옵션은 서버 설정과 일치해야 합니다. 설정을 파싱할 수 있다고 해서 핸드셰이크 매개변수가 올바르다는 뜻은 아닙니다.
필드가 인식되는지 확인하세요. 일부 알 수 없는 필드는 오류를 표시하지 않고 무시될 수 있습니다. ‘가져오기 성공’만으로 모든 옵션이 적용됐다고 단정할 수 없습니다.
호환되는 구독 형식을 사용하세요. 서비스 제공업체가 mihomo용 형식을 제공한다면 해당 형식을 우선 선택하세요. 업그레이드가 필요하다면 설정을 백업한 후 클라이언트나 커널을 변경하세요.

가져오기는 성공했지만 dial timeout, 인증 실패, TLS 핸드셰이크 실패가 발생한다면 문제는 노드 연결 단계로 넘어간 것입니다. 이때는 YAML 들여쓰기를 계속 수정하지 말고 노드 접속 가능 여부, 인증 정보, 서버 설정을 확인하세요. 파싱 성공, 커널 시작, 노드 연결, 서비스 접속은 서로 다른 네 가지 검증 결과입니다.

수정 후 검증 순서와 문의 시 전달할 정보

한 번에 한 단계씩 확인하기

구독을 한 번 수동으로 업데이트해 응답 내용이 비어 있지 않고 HTTP 또는 다운로드 오류가 더는 발생하지 않는지 확인하세요.
테스트 설정을 불러와 로그에 YAML, 프로토콜 유형, 이름 참조 오류가 없는지 확인하세요.
커널이 계속 실행되는지, 포트 충돌이나 권한 부족, 공급자 리소스 로딩 실패가 없는지 확인하세요.
존재가 확인된 노드를 선택해 연결을 테스트한 뒤 실제 애플리케이션에서 규칙이 선택한 아웃바운드를 확인하세요.
필요한 오버라이드와 필터 설정을 복원하고 항목별로 확인한 다음, 마지막으로 예약 업데이트를 다시 활성화하세요.

서비스 제공업체나 프로젝트에 문의할 때 운영체제, 클라이언트 버전, 커널 버전, 실패 시각, HTTP 상태 코드, 민감 정보를 가린 첫 번째 주요 오류를 전달하세요. YAML 문제라면 오류 행 주변의 최소 코드 조각을 첨부하고, 다운로드 문제라면 직접 연결과 현재 프록시 경로에서 각각 어떤 결과가 나왔는지 설명하세요. 인증 정보가 포함된 구독 파일 전체를 제출하지 마세요.

구독 주소가 공개 스크린샷, 문의 게시판, 변환 서비스에 노출됐다면 서비스 제공업체 계정에서 구독 토큰을 재설정한 뒤 모든 기기의 주소를 업데이트하세요. 로컬 기록을 지워도 이미 노출된 접근 권한은 취소되지 않습니다.

점검 순서는 ‘링크 접속 → 응답 형식 → YAML 및 참조 → 커널 호환성’으로 유지하세요. 이 순서를 따르면 서버가 로그인 페이지를 반환하는데 포트를 계속 조정하는 일을 막을 수 있고, 노드 연결 시간 초과를 구독 형식 오류로 오해하지 않을 수 있습니다. 자주 사용하는 필드의 의미는 설정 필드 참고서에서 확인할 수 있습니다. 시스템 프록시와 TUN을 처음 활성화하는 방법은 입문 가이드를 참고하세요.