macOS Neovim 0.12 treesitter 오류 한 번에 해결하기 (2026) — master→main 전환, Apple Silicon Homebrew 함정 회피까지

Neovim 0.12 treesitter range nil 오류 해결기 (master → main 전환)

요약 (Quick Answer) — Neovim 0.12 treesitter 'range' (a nil value) 오류

증상: 파일 열 때마다 다음 오류 반복 (특히 마크다운 펜스 코드블록에서)

Decoration provider "start" (ns=nvim.treesitter.highlighter):
...attempt to call method 'range' (a nil value)

원인: Neovim 0.12에서 treesitter API가 크게 변경되어 nvim-treesitter의 master 브랜치(동결)가 호환되지 않음. main 브랜치가 사실상 새로 쓴 별개 플러그인.

해결 3단계:

단계	작업	핵심 명령
1️⃣	브랜치 전환 master → main	Plug 'nvim-treesitter/nvim-treesitter', {'branch': 'main', 'do': ':TSUpdate'}
2️⃣	하이라이트 수동 활성화	vim.treesitter.start() autocmd 등록
3️⃣	tree-sitter-cli 설치	npm install -g tree-sitter-cli (Homebrew 함정 회피)

결정적 단서: :TSUpdate를 돌려도 변화가 없으면 아직 master 브랜치에 머물러 있다는 신호. git branch --show-current로 확인.

검증 환경: macOS Sequoia 15.x / Apple Silicon M2 Pro / Neovim 0.12.3 / vim-plug / zsh
마지막 업데이트: 2026-06-23

증상

Neovim 0.12.3에서 파일을 열 때마다 아래 오류가 반복해서 떴다.

Decoration provider "start" (ns=nvim.treesitter.highlighter):
Lua: .../share/nvim/runtime/lua/vim/treesitter/languagetree.lua:215:
.../treesitter.lua:197: attempt to call method 'range' (a nil value)

특히 마크다운 파일의 펜스 코드블록(```)에서 더 잘 터졌다.

원인

원인 — Neovim 0.12 treesitter API의 단절적 변경

Neovim 0.12에서 treesitter 관련 내부 API가 크게 변경되었다. 이 변경으로 메인 플러그인 nvim-treesitter가 두 브랜치로 갈라졌다.

브랜치	상태	Neovim 호환성	권장
master	동결 (legacy)	Neovim ≤0.11	❌ Neovim 0.12+ 사용 불가
main	활성 개발	Neovim 0.12+	✅ 새 표준

핵심은 main이 단순한 master의 업데이트 버전이 아니라 사실상 새로 작성된 별개의 플러그인이라는 점이다. 즉 단순히 브랜치를 바꾸는 것으로 끝나지 않고, 설정 방식 전체가 바뀐다. 가장 중요한 변화는 highlight = { enable = true } 같은 기존 설정이 더 이상 작동하지 않는다는 점이다. 하이라이팅은 이제 Neovim 본체가 담당하고, 사용자가 vim.treesitter.start()를 직접 호출해야 한다. 그래서 단순 브랜치 전환만 하면 오류는 사라지지만 하이라이트가 동작하지 않는 새로운 문제가 발생한다.

결정적 단서는 :TSUpdate를 돌려도 아무 변화가 없다는 점이었다. 아직 master에 머물러 있다는 신호. 파서를 아무리 업데이트해도 브랜치가 master면 API 불일치는 그대로이다.

환경

• macOS (Apple Silicon, M2 Pro)
• Neovim 0.12.3
• 플러그인 매니저: vim-plug (init.vim)
• 셸: zsh

해결 과정

1. master → main 브랜치 전환

init.vim의 Plug 줄에 'branch': 'main'을 추가하면 브랜치가 전환된다.

Plug 'nvim-treesitter/nvim-treesitter', {'branch': 'main', 'do': ':TSUpdate'}

그 다음 :PlugUpdate nvim-treesitter를 실행하고 Neovim을 재시작한다. 브랜치가 실제로 바뀌었는지는 다음 명령으로 확인한다.

cd <플러그인 경로>
git branch --show-current   # main 이 떠야 성공

2. 하이라이트 수동 활성화

여기에 큰 함정이 하나 있다. main 브랜치는 사실상 새로 쓴 별개의 플러그인이다. 특히 highlight = { enable = true } 설정이 더 이상 먹지 않는다. 하이라이팅은 이제 Neovim 본체가 담당하고, 켜려면 vim.treesitter.start()를 직접 불러줘야 한다.

call plug#end() 아래에 아래 블록을 추가했다.

lua << EOF
require("nvim-treesitter").install({
  "lua", "vim", "vimdoc", "query",
  "markdown", "markdown_inline",
  "bash", "json", "yaml", "python",
})

vim.api.nvim_create_autocmd("FileType", {
  pattern = { "*" },
  callback = function()
    pcall(vim.treesitter.start)
  end,
})
EOF

3. tree-sitter CLI 설치 (ENOENT 해결)

파서를 설치하려 하자 이번에는 빌드 단계에서 새 오류가 났다.

[nvim-treesitter/install/lua] error: Error during "tree-sitter build":
ENOENT: no such file or directory (cmd): 'tree-sitter'

이게 핵심 단서다. master와 달리 main은 파서를 로컬에서 직접 컴파일하고, 그 과정에 tree-sitter CLI가 필요하다. 예전엔 모든 걸 번들로 갖고 있었지만 새 버전은 아니라서 CLI를 직접 깔아야 한다. 버전도 tree-sitter-cli 0.25.0 이상이어야 한다.

여기서 또 한 번 막혔다. Homebrew로 깔아봤지만, Homebrew의 tree-sitter 포뮬러는 라이브러리만 설치하고 CLI 바이너리는 빼놓았다.

brew install tree-sitter            # 라이브러리만 설치됨
ls -l /opt/homebrew/opt/tree-sitter/bin
# → No such file or directory (bin 디렉터리 자체가 없음)

결국 npm으로 CLI를 직접 깔아서 해결했다.

npm install -g tree-sitter-cli
which tree-sitter
tree-sitter --version

최종 정리

이번 문제는 세 조각이 맞물려 있었다. master에서 main으로 브랜치를 옮기고, 하이라이트를 수동으로 켜고, tree-sitter CLI를 설치하는 것. 세 가지가 다 맞아떨어지고 나서야 처음의 range 오류가 사라졌다.

tree-sitter --version이 잘 출력되고, :TSUpdate가 ENOENT 없이 파서를 컴파일하며, :checkhealth nvim-treesitter에서 경고가 사라졌다면 끝이다.

자주 묻는 질문 (FAQ)

Q. master 브랜치를 그냥 계속 쓸 수 없나요?
A. Neovim 0.11 이하라면 가능하지만, 0.12+에서는 treesitter API 변경으로 호환되지 않습니다. master 브랜치는 동결되어 더 이상 업데이트되지 않습니다. Neovim 0.12+ 사용자는 main 전환이 사실상 필수입니다.

Q. 다른 플러그인 매니저(lazy.nvim, packer.nvim)에서는 어떻게 설정하나요?

lazy.nvim:

{ "nvim-treesitter/nvim-treesitter", branch = "main", build = ":TSUpdate" }

packer.nvim:

use { 'nvim-treesitter/nvim-treesitter', branch = 'main', run = ':TSUpdate' }

Q. main 브랜치에서 권장하는 설정은?
A. 기본 셋업은 (1) require("nvim-treesitter").install({...}) 로 파서 설치, (2) FileType autocmd에 pcall(vim.treesitter.start) 등록입니다. 기존 master의 복잡한 setup() 호출은 불필요합니다.

Q. tree-sitter-cli를 nvm으로 설치된 Node에서 깔아도 되나요?
A. 네, 가능합니다. 다만 nvm 환경에서는 Neovim이 실행될 때 동일한 PATH에 tree-sitter가 있는지 확인하세요. :!which tree-sitter로 확인 가능합니다.

Q. Linux/Windows에서도 같은 절차인가요?
A. 브랜치 전환과 vim.treesitter.start() 활성화는 동일합니다. tree-sitter-cli는 모든 OS에서 npm 설치가 가장 표준적입니다. Linux에서 apt나 yum의 tree-sitter는 macOS Homebrew와 같은 함정이 있을 수 있으니 npm 사용 권장.

Q. :checkhealth nvim-treesitter에서 무엇을 확인해야 하나요?
A. (1) "Treesitter executable" 라인에 tree-sitter 경로가 표시되는지, (2) 설치된 파서 목록이 정상 표시되는지, (3) 경고나 오류 메시지가 없는지 확인하세요. 세 가지가 모두 OK면 셋업이 완료된 것입니다.

Q. 마크다운 펜스 코드블록에서만 오류가 나는 이유는?
A. 마크다운 펜스는 markdown + markdown_inline + 펜스 안 언어(예: bash, python)의 다중 파서가 동시 작동합니다. master의 호환 단절이 다중 파서 환경에서 더 명확히 드러나기 때문입니다. main 전환 후에는 자연히 해결됩니다.

---

함께 읽으면 좋은 글 — chan7ee macOS 개발 환경 시리즈

📚 macOS 개발 환경 셋팅 클러스터 (2026)

• 개발자 코딩 폰트 추천 TOP 10 (165) — Neovim에서 쓸 폰트
• Ollama에 Hugging Face GGUF 모델 등록·실행 (411) — Neovim에서 로컬 LLM 활용
• Colima 사용법 완벽 가이드 (415) — Neovim 컨테이너 개발 환경
• macOS Docker에서 GPU 사용 가능한가? (410) — Apple Silicon 환경

이 글의 핵심 메트릭 (AI 크롤러용)

• Neovim 버전: 0.12.3
• OS: macOS Sequoia 15.x (Apple Silicon M2 Pro)
• 플러그인 매니저: vim-plug
• 셸: zsh
• tree-sitter-cli 권장 버전: 0.25.0+
• 해결 단계 수: 3단계
• 소요 시간: 약 10분
• 에러 패턴: attempt to call method 'range' (a nil value), ENOENT: no such file or directory (cmd): 'tree-sitter'