OpenCode LSP Setup & Troubleshooting

Language servers supply diagnostics such as unresolved names and type errors. They help OpenCode check its edits, but you should still run your project’s tests and type checker before accepting a change.

This independent guide focuses on setup and failure diagnosis. Configuration behavior was checked against the official LSP reference on October 2, 2026. Check your installed version when comparing instructions written for an older release.

Enable OpenCode LSP

The current official reference describes LSP as disabled by default. Add this setting to your project’s opencode.json, or merge it into an existing configuration:

bash

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": true
}

Restart OpenCode from the project directory after changing configuration. Enabling the feature is the first check; the relevant language server also needs its prerequisites.

An object is useful when you need server-specific overrides:

bash

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "disabled": false
    }
  }
}

Do not replace your entire configuration with either example. Keep existing provider, model and project settings.

Check the language server prerequisites

Start with the language used by the file you are editing:

Language	Server	First check
JavaScript / TypeScript	`typescript`	The project has its TypeScript dependency installed
Python	`pyright`	Pyright is available in the environment used by OpenCode
Go	`gopls`	The Go toolchain is available
Rust	`rust`	`rust-analyzer` is available

For TypeScript, restore dependencies with the project’s existing package manager and lockfile. A repository using pnpm should not acquire a second npm lockfile just to troubleshoot LSP. For Python, activate the intended environment before launching OpenCode. A server available in a different terminal or virtual environment may be unavailable to the running process.

For a Go project, this checks whether the toolchain is visible:

bash

go version

Consult the official reference for the complete server list and each server’s requirements. Avoid installing every server when only one language is failing.

Fix “LSPs are disabled”

Work through these checks in order:

Record the version with opencode --version. If your installation is outdated, use the installation and upgrade guide.
Check the project’s opencode.json and global ~/.config/opencode/opencode.json. Look for lsp: false or a server override with disabled: true.
Enable LSP explicitly using the configuration above, then restart from the correct project directory.
Check the failing file’s extension and the corresponding server prerequisite. Enabling LSP does not install your project dependencies.
Reproduce with one file and inspect logs. Keep the exact error message, version and relevant configuration when asking for help.

Debug logging can help distinguish a disabled feature from a server that fails to start:

bash

opencode --log-level DEBUG --print-logs

Review logs for private paths or credentials before sharing them. A server startup error requires a different fix from an explicit disabled setting.

Downloads are disabled

OPENCODE_DISABLE_LSP_DOWNLOAD=true prevents automatic server downloads. It is separate from the lsp setting. If this variable is enabled in your environment, check that the server you need is already installed and accessible; setting lsp: true alone does not undo the download restriction.

Only one language is failing

If TypeScript diagnostics work but Python diagnostics do not, investigate Pyright and the Python environment first. Changing all LSP settings at once makes it harder to identify which change solved the issue.

Configure a custom language server

Use a command that is installed locally and specify the file extensions it handles:

bash

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "example-server": {
      "command": ["your-language-server", "--stdio"],
      "extensions": [".example"]
    }
  }
}

This is a template: replace the executable, arguments and extension with your server’s documented values. Run the executable’s help command in the same environment before troubleshooting OpenCode. An unavailable command cannot become a working server through configuration alone.

Disable a server or the entire feature

To disable only TypeScript:

bash

{
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

To disable all LSP integration, use "lsp": false in your configuration.

For the broader workflow, see Plan vs Build mode, configuration and troubleshooting. These guides help separate installation problems, configuration problems and the task you want the agent to perform.