Fix: Opencode `server.root Is Not A Function` Error

Hey everyone! 👋

I've been wrestling with this rather perplexing error in Opencode, and I figured I'd share my journey and hopefully get some insights from you all. The error I'm encountering is a TypeError: server.root is not a function, which pops up when Opencode tries to use my Language Server Protocol (LSP) setup. It's a bit of a head-scratcher, especially since everything seems to be configured correctly (at least, as far as I can tell!).

TypeError: server.root is not a function. (In 'server.root(file2, App.info())', 'server.root' is undefined)

It seems like the server.root function is either not defined or not being correctly exposed by my LSP server. This is particularly confusing because the LSP server itself appears to be running smoothly outside of Opencode.

To give you a clearer picture, here’s my Opencode configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "phpactor": {
      "command": [
        "~/.local/share/nvim/mason/bin/phpactor",
        "language-server"
      ],
      "extensions": [
        ".php"
      ],
      "initialization": {
        "indexer.follow_symlinks": true,
        "language_server_phpstan.enabled": true
      }
    }
  },
  "model": "anthropic/claude-sonnet-4-20250514",
  "theme": "system"
}

As you can see, I'm using Phpactor as my LSP for PHP development. I've specified the command to run the language server, the file extensions it should handle, and some initialization options. Everything looks pretty standard, but clearly, something is amiss.

Diving Deep: Understanding the server.root Error

Let's break down this error message: TypeError: server.root is not a function. This error typically arises when you're trying to call something as a function that either isn't a function or is undefined. In this context, server likely refers to the LSP server instance, and root is presumably a method that Opencode expects to be available on that instance. The fact that it's showing as undefined suggests that the server object doesn't have a root property defined, or the property exists but isn't a function.

Possible Culprits and Troubleshooting Steps

1. LSP Server Implementation:

   The first place to investigate is the LSP server itself. Is the root function actually part of the Phpactor LSP? It's possible that Opencode is expecting a method that Phpactor doesn't provide, or that the method has a different name. To verify this, I'd recommend diving into the Phpactor LSP documentation or source code. Look for any methods related to project root detection or workspace initialization. This might give us a clue as to whether root is indeed the correct method name.

   • Checking Phpactor's Capabilities: LSP servers advertise their capabilities through a handshake process. When Opencode connects to Phpactor, it should receive a list of methods and features that Phpactor supports. We need to ensure that root (or an equivalent method) is part of this advertised capability set. If it's not, then Opencode is trying to use a function that the server doesn't claim to provide.

   • Debugging the LSP Server: If possible, try running Phpactor LSP in a debug mode. This might provide more verbose logging or allow us to step through the code and see exactly what's happening when Opencode tries to call server.root. Debugging can reveal whether the method is being called at all, and if so, why it's not defined.

2. Opencode's LSP Client Logic:

   The issue might not be with the LSP server, but with how Opencode is interacting with it. Opencode has its own LSP client implementation that handles communication with the server. It's possible that there's a bug in Opencode's code that causes it to incorrectly call server.root or to misinterpret the server's capabilities.

   • Examining Opencode's LSP Client: We'd need to delve into Opencode's source code to understand how it discovers and calls LSP methods. Look for the section of code that handles the initialization handshake and method invocation. This might reveal whether Opencode is making assumptions about the server's API that aren't valid for Phpactor.

   • Checking Opencode's Configuration Handling: It's also worth checking how Opencode handles LSP configurations. Is it correctly parsing the lsp section of my configuration file? Is it passing the correct initialization options to Phpactor? A misconfiguration could lead to Opencode attempting to use methods that aren't available in the current server setup.

3. Version Mismatch:

   It's always a good idea to check for version incompatibilities. Are you using a version of Opencode that's compatible with your version of Phpactor? Sometimes, updates to either the client or the server can introduce breaking changes. Check the documentation for both Opencode and Phpactor to see if there are any known compatibility issues.

   • Testing with Different Versions: Try downgrading or upgrading either Opencode or Phpactor (or both) to see if the issue resolves itself. This can help pinpoint whether a specific version introduced the bug.

4. Pathing and Environment Issues:

   Sometimes, seemingly unrelated environment issues can cause bizarre errors. Double-check that the path to your Phpactor executable is correctly configured and that all necessary dependencies are installed and accessible. A missing dependency or an incorrect path could prevent Phpactor from initializing properly, leading to unexpected behavior.

   • Verifying Executable Paths: Ensure that the path specified in the command array in your Opencode configuration is correct. Try running the Phpactor language server command directly from your terminal to see if it starts up without errors. If it doesn't, then there's likely an issue with your Phpactor installation or environment.

   • Checking Environment Variables: Phpactor might rely on certain environment variables to function correctly. Consult the Phpactor documentation to see if any specific environment variables are required. Make sure these variables are set correctly in your shell environment.

Real-World Analogy: The Restaurant Menu

Think of this situation like going to a restaurant and trying to order a dish that's not on the menu. Opencode is the customer, Phpactor is the chef, and the LSP protocol is the menu. Opencode (the customer) tries to order the server.root dish, but if Phpactor (the chef) doesn't have that dish on the menu (its capabilities), you'll get an error. The waiter (the LSP client) is supposed to know what's on the menu and guide the customer accordingly. If the waiter is confused or the menu is outdated, you end up with a frustrating situation.

Sharing My Findings and Seeking Help

I've already started digging into these areas, but I'm still stumped. I've checked the Phpactor documentation, but I haven't found a direct reference to a root method. I'm also in the process of examining Opencode's LSP client code, but it's a complex codebase, and I could use some guidance.

Has anyone else encountered this issue, or does anyone have experience with Phpactor and Opencode that might shed some light on this? Any suggestions on where to look next or debugging strategies would be greatly appreciated!

I'll keep you guys updated on my progress, and hopefully, we can crack this nut together! 🤝

Updates and Next Steps

Update 1: I've been doing some more digging, and I've discovered that the server.root method is indeed not a standard part of the LSP specification. It seems like Opencode might be making an assumption about the LSP server's API that isn't universally true. This points towards a potential issue in Opencode's LSP client implementation.

Next Steps:

• File an Issue with Opencode: I think the next logical step is to file an issue with the Opencode project, describing the problem and my findings. This will bring the issue to the attention of the Opencode maintainers, who might have a better understanding of the codebase and be able to provide a fix.
• Contribute a Fix (Maybe): If I can get a better grasp of Opencode's LSP client code, I might even try to contribute a fix myself. However, I want to make sure I fully understand the implications of any changes before submitting a pull request.
• Explore Alternative LSP Clients: In the meantime, I might explore alternative LSP clients that are known to work well with Phpactor. This could help me isolate whether the issue is specific to Opencode's implementation.

I'm still open to suggestions and insights from the community, so please don't hesitate to chime in if you have any ideas! Let's get this resolved! 💪