Developer Hub

Troubleshooting

A focused guide for the troubleshooting stage of extension development. coc.nvim extensions expose an activate(context) entry point to the Node.js extension host.

Troubleshoot an extension

Separate extension-host failures from language-server failures, then collect the smallest reproducible trace without exposing credentials, private source, or machine-specific secrets.

1. Confirm the extension runtime

Run :CocInfo and record coc.nvim, Node.js, editor, and extension versions.
Run :CocList extensions and confirm the extension is loaded and activated.
Use :CocCommand workspace.showOutput to inspect the extension or language-client output channel.

2. Verify the package

Run npm run typecheck and npm run build.
Run both npm run test:nvim and npm run test:vim.
Run npm pack --dry-run and confirm main, files, and compiled output agree.

Extension-host logs

Extension console.log, console.error, and ExtensionContext.logger output is routed to :CocOpenLog. Do not write to process.stdout or process.stdin; coc.nvim uses stdio for its editor transport.

Extension logger

1	exports.activate = async context => {
2	context.logger.info(`Extension loaded from ${context.extensionPath}`)
3	context.logger.debug('resolved configuration', { enabled: true })
4	}

vimrc · temporary trace settings

1	" Set these before coc.nvim starts.
2	let $NVIM_COC_LOG_LEVEL = 'trace'
3	let $NVIM_COC_LOG_FILE = '/tmp/coc.log'
4
5	" Enable the Vim/Neovim-to-Node client log only when RPC needs inspection.
6	let g:node_client_debug = 1
7	let $NODE_CLIENT_LOG_FILE = '/tmp/coc-client.log'

Restart the editor after changing these environment variables, tail /tmp/coc.log, reproduce once, then remove trace logging. Vim channel errors from callVim(), evalVim(), or exVim() may require $COC_VIM_CHANNEL_ENABLE = '1' or coc#client#open_log().

Debug a language server

Start with service discovery before enabling protocol traces. A language client only starts when its filetypes and workspace conditions match the current buffer.

1. Inspect service state. Run :CocList services to see each service id, state, and filetypes. IDs beginning with languageserver come from coc-settings.json; other IDs come from extensions.
2. Confirm the document language. Run :CocCommand document.echoFiletype. Check the server command, executable PATH, root patterns, working directory, and initialization options.
3. Open the output channel. Run :CocCommand workspace.showOutput. Select the server and reproduce the startup or request failure.
4. Enable protocol tracing only when needed. Set the server’s trace.server setting to verbose, restart the service, and redact document text and paths before sharing the trace.

coc-settings.json · custom server trace

1	{
2	"languageserver": {
3	"ccls": {
4	"command": "ccls",
5	"filetypes": ["c", "cpp", "objc", "objcpp"],
6	"trace.server": "verbose",
7	"initializationOptions": {
8	"cacheDirectory": "/tmp/ccls"
9	}
10	}
11	}
12	}

Node.js language servers: a server that supports Node IPC can expose the inspector through an extension-specific execArgv setting, for example ["--nolazy", "--inspect-brk=6045"]. Start the service, then attach through chrome://inspect. Do not add this to unrelated native servers.

Source maps and debugger attachment

Build development source maps and load source-map-support/register through g:coc_node_args when bundled stack traces point only at generated code. Add --experimental-vm-modules so the extension host can load ESM modules through Node’s VM APIs. This slows startup, so keep it temporary. For an extension-host breakpoint, add --inspect-brk=5858, restart coc.nvim, and attach a Node-compatible debugger.

Build source maps

1	NODE_ENV=development npm run build
2	npm install -g source-map-support
3	npm root -g

vimrc · debugger arguments

1	let g:coc_node_args = [
2	'-r', '/path/from/npm-root/source-map-support/register',
3	'--experimental-vm-modules',
4	'--nolazy', '--inspect-brk=5858'
5	]

Issue report template

1	Environment:
2	- coc.nvim: paste the version from :CocInfo
3	- Node.js: node --version
4	- Editor: vim --version or nvim --version
5	- Extension: package.json name and version
6
7	Reproduction:
8	1. Start with a clean workspace and the smallest package/config that fails.
9	2. List the exact command or edit that triggers the problem.
10	3. Record the expected result and the observed result.
11	4. Attach a redacted :CocOpenLog excerpt and the failing coc-test lane.
12
13	Privacy:
14	- Remove tokens, private paths, proxy credentials, project source, and
15	private registry URLs before sharing logs or a package tarball.

Debug coc.nvim and extensionsLogs, source builds, editor transport, source maps, and inspector attachment.Debug language serversService state, filetypes, output channels, protocol traces, and Node server debugging.

Use the site Troubleshooting Center for user-facing diagnosis. This developer guide is for extension and language-server maintainers.