neoclide/coc.nvim · warning · Error

Unable to perform semantic highlights for current buffer.

Error message

Unable to perform semantic highlights for current buffer.

What it means

coc.nvim throws this when `CocAction('semanticHighlights')` (SemanticTokensHandler.highlightCurrent) is called for the current buffer but no semantic-tokens highlighting item exists for that buffer, or the item exists but semantic highlighting is disabled for it. It is a guard against forcing a highlight operation on a buffer that has no registered semantic-token provider/state.

Source

Thrown at src/handler/semanticTokens/index.ts:173

  public closeFloat(): void {
    floatFactory?.close()
  }

  public async getCurrentItem(): Promise<SemanticTokensBuffer | undefined> {
    let buf = await this.nvim.buffer
    return this.getItem(buf.id)
  }

  public getItem(bufnr: number): SemanticTokensBuffer | undefined {
    return this.highlighters.getItem(bufnr)
  }
  /**
   * Force highlight of current buffer
   */
  public async highlightCurrent(): Promise<void> {
    let item = await this.getCurrentItem()
    if (!item || !item.enabled) throw new Error(`Unable to perform semantic highlights for current buffer.`)
    await item.forceHighlight()
  }

  /**
   * Show semantic highlight info in temporarily buffer
   */
  public async showHighlightInfo(): Promise<void> {
    let bufnr = await this.nvim.call('bufnr', ['%']) as number
    workspace.getAttachedDocument(bufnr)
    let { nvim } = this
    let item = this.highlighters.getItem(bufnr)
    let hl = new Highlighter()
    nvim.pauseNotification()
    nvim.command(`vs +setl\\ buftype=nofile __coc_semantic_highlights_${bufnr}__`, true)
    nvim.command(`setl bufhidden=wipe noswapfile nobuflisted wrap undolevels=-1`, true)
    nvim.call('bufnr', ['%'], true)
    let res = await nvim.resumeNotification()
    hl.addLine('Semantic highlights info', headGroup)

View on GitHub (pinned to 50e974d969)

Solutions

1. Ensure a language server with semanticTokensProvider capability is attached (run :CocCommand workspace.showOutput or :CocInfo to confirm the server started).
2. Enable semantic tokens: set "semanticTokens.enable": true in coc-settings.json (and highlight.enable if relevant).
3. Wait for the server to finish initialization or retry after buffer attach; call the action from a User autocmd (e.g. CocGitStatusChanged / BufEnter after attach).
4. Wrap the call in try/catch and treat the error as 'no semantic highlights available for this buffer' rather than a hard failure.

Example fix

// before
CocAction('semanticHighlights')  // throws in non-LSP buffer

// after
" user command guarded in vimscript
try
  call CocAction('semanticHighlights')
catch
  echom 'Semantic highlights unavailable: ' . v:exception
endtry

let highlights
try {
  highlights = await CocAction('semanticHighlights')
} catch (e) {
  // buffer has no semantic tokens provider or it's disabled
  highlights = []
}

When it happens

Trigger: Calling CocAction('semanticHighlights') (or the JS API highlightCurrent) in a buffer that (a) has no attached language server providing semantic tokens, (b) is not a semanticTokensHighlights item (getCurrentItem returns undefined), or (c) has semantic highlighting disabled for that buffer/document (item.enabled is false).

Common situations: Running the command in a plain text/markdown buffer without an LSP; the language server doesn't advertise the `semanticTokensProvider` capability; semanticTokens is disabled globally via `semanticTokens.enable: false` or per-filetype; calling the action during VimEnter before the server finishes initialization; buffer isn't attached because coc hasn't opened it as a document.

Related errors

• Semantic tokens highlight not enabled for current filetype:
• SemanticTokens provider not found for ${this.doc.uri}
• Inlay hint provider not found for current document
• Filetype "${this.doc.filetype}" not enabled by inlayHint con
• Failed to resolve link target

AI-assisted analysis of neoclide/coc.nvim@50e974d969 (2026-08-31). Data as JSON: /api/errors/ddf1797ea0fee5d8. Report an issue: GitHub.