태블로 서버 'does not match a known configuration key' 에러 해결하기

태블로 서버(Tableau Server) 환경 간 설정을 이전하거나 마이그레이션할 때, tsm settings export로 추출한 구성 파일을 신규 서버에 tsm settings import로 반영하는 과정에서 다음과 같은 오류가 발생할 수 있습니다.

Configuration error: At least one configuration value you specified does not match a known configuration key.
Use this parameter to override unknown key error: --force-keys

Root Cause

이 오류는 가져오려는 JSON 설정 파일 내에 현재 대상 서버의 TSM 스키마에 등록되지 않은 구성 키(Unknown Key)가 포함되어 있을 때 발생합니다.

서로 다른 환경 간에 설정을 이전하거나 버전 차이가 있는 서버로 마이그레이션할 때, 원본(Source) 서버의 설정 파일에 포함된 특정 파라미터가 대상(Target) 서버의 TSM 유효성 검사기(Schema Validator) 사전에 존재하지 않으면 무결성 보호를 위해 가져오기 작업을 즉시 차단합니다.

Solution

이 문제는 두 가지 방법으로 해결할 수 있습니다.

방법 1. --force-keys 옵션 사용 (권장)

에러 메시지에 안내된 플래그를 추가하여, 대상 서버에서 인식하지 못하는 키는 건너뛰고 유효한 설정값만 선별하여 가져옵니다.

tsm settings import -f <설정파일명>.json --force-keys
tsm pending-changes apply

적용 전 tsm pending-changes list를 실행하여 의도한 환경 설정값만 대기 목록에 정상적으로 올라왔는지 확인합니다.

방법 2. JSON 파일에서 유효하지 않은 키 직접 제거

내보낸 JSON 파일을 텍스트 에디터로 열어 에러 메시지에 나열된 키 항목들을 검색 후 삭제한 뒤 다시 임포트합니다.