Zed: Fixing ZLS Unresponsive Bug After V0.196.6

by Mei Lin 48 views

Hey guys! Are you experiencing issues with the Zig Language Server (ZLS) in Zed? Specifically, is your ZLS becoming unresponsive after single actions since upgrading to v0.196.6? You're not alone! This article dives deep into this frustrating problem, offering insights, troubleshooting steps, and potential solutions. We'll cover everything from the initial bug report to the technical details, ensuring you have a solid understanding of the issue and how to tackle it. Let's get started!

Understanding the ZLS Unresponsiveness Issue

The Initial Problem: ZLS Stops Responding

The core issue? The Zig Language Server (ZLS), which is essential for providing features like code completion, hover information, and diagnostics in Zed, simply stops responding after performing a single action. Imagine typing a character, hovering over a symbol, or even just adding a new line, and boom—the ZLS freezes up. This means no more helpful suggestions, no quick info pop-ups, and no real-time error checking. Frustrating, right? This problem surfaced after Zed version 0.196.6 and has persisted through subsequent versions, including 0.199.3.

Reproducing the Issue: A Step-by-Step Guide

To truly understand the issue, let's walk through how to reproduce it. This way, you can confirm if you're facing the same problem and have a clear process for testing solutions.

  1. Open any Zig project in Zed: This issue isn't specific to one project; it seems to affect all Zig projects.
  2. Wait for ZLS to initialize: Once you open the project, the ZLS should start up. Wait for it to finish initializing.
  3. Perform a single action: This is where the problem kicks in. Try any of these actions:
    • Hover your mouse over a symbol in your code.
    • Type a character in a Zig file.
    • Add a new line.
  4. Observe ZLS's unresponsiveness: After performing one of these actions, the ZLS should stop responding. You'll notice that hover information doesn't appear, code completions don't pop up, and diagnostics aren't updated.

Expected vs. Actual Behavior: What Should Happen?

Expected Behavior: ZLS should continue working smoothly after any editor actions. You should be able to hover over symbols and get information, see code completions as you type, and receive real-time diagnostics.

Actual Behavior: ZLS becomes unresponsive after a single editor action. To get it working again, you have to manually restart it using the “editor: restart language server” command from the command palette. Even then, it only works briefly before freezing up again.

Technical Details: Environment and Versions

To help you (and the Zed team) understand the scope of this issue, here are the environment details where this problem was initially reported:

  • OS: macOS 15.5 (Apple M1 Pro)
  • Zig: 0.14.1
  • ZLS: 0.14.0
  • Zed versions affected: All versions after 0.196.6 (f80bd3a66b03049475d936e2da848431fa0c7e4e)
  • Last working version: Zed 0.196.6
  • Latest tested version: Zed Preview 0.199.3 (d6223feb34dca3c6718260920ec5e13bc31c7581)

This information is crucial for identifying potential patterns and narrowing down the cause of the issue. If you're experiencing this, make sure your environment aligns with these details or note any differences.

Diving Deeper: Error Logs and Settings

To truly diagnose the problem, let's examine the error logs and settings that might shed some light on what's going wrong. These technical details can often provide clues that lead to a solution.

Examining Relevant Zed.log Errors

Error logs are your best friend when troubleshooting. They often contain messages that pinpoint the exact problem. Here’s an example of the type of errors seen in the Zed.log:

2025-08-12T11:16:03+10:00 ERROR [lsp] Cancelled LSP request task for "textDocument/documentHighlight" id 65 which took over 120s
2025-08-12T11:16:03+10:00 WARN  [project::lsp_store] Get document highlights via zls failed: Request timed out
2025-08-12T11:16:03+10:00 ERROR [editor] Get document highlights via zls failed: Request timed out
2025-08-12T11:16:03+10:00 ERROR [lsp] Cancelled LSP request task for "textDocument/codeAction" id 66 which took over 120s
2025-08-12T11:16:03+10:00 WARN  [project::lsp_store] Get code actions via zls failed: Request timed out
2025-08-12T11:16:03+10:00 ERROR [project] Get code actions via zls failed: Request timed out

These errors indicate that LSP (Language Server Protocol) requests are timing out. Specifically, requests for document highlights and code actions are being cancelled after 120 seconds. This strongly suggests that the ZLS is either taking too long to respond or is not responding at all, leading to the unresponsiveness we're seeing.

Reviewing settings.json

Your Zed settings can also play a role in how the ZLS behaves. Certain settings might inadvertently cause conflicts or performance issues. Here’s an example of a settings.json configuration that was used when the issue was reported:

{
  "Zig": {
    "code_actions_on_format": {
      "source.fixAll": true
    }
  }
}

In this case, the code_actions_on_format setting is enabled, which means Zed will try to apply code actions whenever you format your code. While this can be helpful, it could also potentially trigger a large number of requests to the ZLS, possibly contributing to the timeout issues. It's worth experimenting with disabling this setting to see if it resolves the problem.

Additional Observations

  • Working in 0.196.6: It's crucial to note that ZLS continues to function correctly when using Zed version 0.196.6. This points to a change introduced after this version as the likely cause.
  • Project Agnostic: The issue isn't tied to a specific Zig project. This means it’s likely a global setting or interaction between Zed and ZLS causing the problem, rather than something specific to your codebase.
  • Mise Installation: ZLS was installed via Mise, a tool for managing project-specific tool versions. While Mise itself isn't necessarily the culprit, it's another variable to consider when troubleshooting.

Potential Causes and Troubleshooting Steps

Okay, so we've laid out the problem, reproduced it, and examined the technical details. Now, let's get to the juicy part: figuring out what's causing this and how to fix it! Based on the information we've gathered, here are some potential causes and troubleshooting steps you can try.

1. Language Server Protocol (LSP) Timeouts

The Problem: The error logs clearly indicate LSP request timeouts. This means Zed is sending requests to ZLS, but ZLS isn't responding within the expected timeframe.

Troubleshooting Steps:

  • Increase Timeout Settings: Zed might have a default timeout setting for LSP requests. Try increasing this timeout to see if it gives ZLS more time to respond. You can typically find LSP settings in Zed's configuration.
  • Check ZLS Performance: Monitor ZLS's CPU and memory usage. If it's consistently high, ZLS might be struggling to handle requests, leading to timeouts.
  • Restart ZLS Manually: You've already been doing this, but it's worth reiterating. Restarting ZLS via the command palette can provide temporary relief.

2. Resource Constraints

The Problem: Your system might not have enough resources (CPU, memory) to handle Zed and ZLS simultaneously, especially if you're working on a large project.

Troubleshooting Steps:

  • Close Unnecessary Applications: Free up resources by closing other applications that might be consuming CPU or memory.
  • Monitor System Resources: Use your system's task manager (Activity Monitor on macOS, Task Manager on Windows) to monitor CPU and memory usage. Look for spikes or consistently high usage.
  • Increase System Resources: If you're consistently running out of resources, consider upgrading your hardware (e.g., adding more RAM).

3. Extension Conflicts

The Problem: Other Zed extensions might be interfering with ZLS's operation.

Troubleshooting Steps:

  • Disable Other Extensions: Try disabling other Zed extensions one by one to see if any of them are causing conflicts. This can help you isolate the problematic extension.
  • Check Extension Settings: Review the settings of your other extensions to see if any of them might be interacting with ZLS in unexpected ways.

4. Zed Bugs

The Problem: The issue might be a bug in Zed itself, specifically in how it handles LSP or interacts with ZLS.

Troubleshooting Steps:

  • Update Zed: Make sure you're running the latest version of Zed. Bug fixes are often included in updates.
  • Rollback Zed Version: Since the issue started after 0.196.6, try rolling back to that version to see if the problem goes away. This can help confirm if a Zed update introduced the bug.
  • Report the Issue: If you suspect a Zed bug, report it to the Zed team on their issue tracker. Provide as much detail as possible, including your environment, steps to reproduce the issue, and any error logs.

5. ZLS Configuration Issues

The Problem: There might be specific ZLS configurations that are causing the issue.

Troubleshooting Steps:

  • Review ZLS Settings: Check your ZLS settings (if any) to see if there are any configurations that might be causing performance issues or conflicts.
  • Try Default ZLS Configuration: If you've customized your ZLS settings, try reverting to the default configuration to see if that resolves the issue.

6. Mise-Related Issues

The Problem: Although less likely, there could be an issue related to how ZLS is being managed via Mise.

Troubleshooting Steps:

  • Update Mise: Ensure you're using the latest version of Mise.
  • Reinstall ZLS via Mise: Try uninstalling and reinstalling ZLS using Mise.
  • Try a Different Installation Method: As a test, try installing ZLS outside of Mise to see if the issue persists. This can help determine if Mise is involved.

Solutions and Workarounds

So, what can you do right now to alleviate this issue while we wait for a permanent fix? Here are some solutions and workarounds you can try:

  1. Restart ZLS Frequently: This is the most immediate workaround. Use the “editor: restart language server” command whenever ZLS becomes unresponsive. It's not ideal, but it allows you to keep working.
  2. Rollback to Zed 0.196.6: If you need a stable environment, rolling back to Zed 0.196.6 is a solid option since ZLS works correctly in that version.
  3. Disable Code Actions on Format: As mentioned earlier, disabling the code_actions_on_format setting in your settings.json might reduce the number of requests sent to ZLS, potentially preventing timeouts.
  4. Monitor Resource Usage: Keep an eye on your CPU and memory usage. If you notice high usage, try closing unnecessary applications or increasing your system resources.
  5. Report the Issue to Zed: If you haven't already, report the issue to the Zed team. The more information they have, the better they can diagnose and fix the problem.

Zed Version and System Specs (Recap)

For clarity, let's recap the environment details where this issue was initially reported:

  • Zed: v0.199.3 (Zed Preview)
  • OS: macOS 15.5.0
  • Memory: 32 GiB
  • Architecture: aarch64

Conclusion: Staying Patient and Proactive

The ZLS unresponsiveness issue in Zed after v0.196.6 is undoubtedly frustrating. However, by understanding the problem, examining error logs, and trying various troubleshooting steps, you can take a proactive approach to finding a solution or workaround. Remember, the Zed team is actively working to improve the editor, and your feedback is invaluable in this process. Stay patient, keep experimenting, and report your findings. Together, we can make Zed an even better coding environment!

I hope this comprehensive guide helps you navigate the ZLS unresponsiveness issue in Zed. Keep coding, and don't let a little bug slow you down! If you have any other questions, feel free to ask!