Fixing OpenTofu's Schema Errors In Local Module Files

Alex Johnson

-Oct 11, 2025

Fixing OpenTofu's Schema Errors In Local Module Files

Hey everyone, let's dive into a common headache many of us face when working with OpenTofu and its language server, tofu-ls. Specifically, we're tackling the pesky "schema not found" error that pops up when you're trying to get those sweet, sweet completions and go-to-definition features working within your local module files. If you've been scratching your head wondering why your editor feels like it's suddenly lost its OpenTofu mojo, you're in the right place! This guide will break down the issue, why it happens, and hopefully, how to get your OpenTofu workflow back on track. We will fix Schema not found when opening local module files.

Understanding the Problem: Schema Not Found

So, what's the deal with this "schema not found" error? Well, the tofu-ls (OpenTofu Language Server) relies on schemas to understand the structure of your OpenTofu code. These schemas provide information about providers, resources, variables, and all the other components that make up your infrastructure-as-code. When you open a main.tf file, tofu-ls needs to load these schemas to provide features like auto-completion, syntax highlighting, and navigation. The problem arises when you're working with local modules—those neatly organized directories containing reusable OpenTofu code. Specifically, the language server struggles to locate the necessary schemas when you open a main.tf file located within a local module, even if everything works fine in your root main.tf.

Let's paint a picture with a typical project structure to illustrate this:

. 
├── modules 
│   └── unit 
│       ├── main.tf 
│       ├── variables.tf 
│       └── versions.tf 
├── .terraform 
│   ├── modules 
│   │   └── modules.json 
│   ├── providers 
│   │   └── registry.opentofu.org 
│   └── plugin_path 
├── .terraform.lock.hcl 
├── flake.lock 
├── flake.nix 
└── main.tf

In this setup, opening the root main.tf file with your editor (like Vim, as mentioned in the original report) and tofu-ls works flawlessly. You get all the goodies you expect. But, if you try to open ./modules/unit/main.tf, the language server throws a fit, and you get the "schema not found" error. This means no auto-completions, no helpful hints, and basically, your editor becomes a glorified text editor. The language server is unable to preload schema, which can cause an error.

The core issue is that tofu-ls isn't correctly identifying or accessing the necessary provider schemas when it's pointed at a file within a nested module. This often happens because of how the language server determines the project root or the path to find the providers. When it can't find the schema, it can't understand your code, and you're left with a frustrating experience.

Examining the Error Message

Let's break down a typical error message to understand what's happening:

[Stderr - 11:14:17 AM] ... schema.go:130: preloaded schema not available for registry.opentofu.org/fastly/fastly

This message tells us a few important things:

schema.go:130: This points to the specific file and line number within the tofu-ls codebase where the error occurred. It's useful if you want to dig deeper or contribute to a fix.
preloaded schema not available: This is the heart of the problem. The language server is trying to use a preloaded schema for the fastly/fastly provider but can't find it.
registry.opentofu.org/fastly/fastly: This identifies the specific provider the language server is trying to load a schema for. It suggests that the language server is having trouble locating the schema information for the fastly/fastly provider.

Essentially, the language server knows it needs the schema for the fastly/fastly provider (as defined in your OpenTofu configuration), but it can't find it when you open a file in the nested module. This is the crux of the problem, and resolving this is the key to getting your editor working correctly.

Reproducing the Issue: Steps to Trigger the Error

Reproducing the issue is usually pretty straightforward. Here's how you can trigger the "schema not found" error:

Set up a basic OpenTofu project: Create a project with a structure similar to the one described above. Make sure you have a root main.tf and a local module (e.g., modules/unit/).
Define providers: In both your root main.tf and the versions.tf file within your module, specify the required providers. For example, you might include the fastly/fastly provider, as shown in the original example:
```
terraform {
  required_providers {
    fastly = {
      source  = "fastly/fastly"
      version = "~> 8.3.0"
    }
  }
}
```
Initialize OpenTofu: Run tofu init in the root directory of your project. This will download the necessary provider plugins and set up the .terraform directory.
Open the root main.tf: Open the main.tf file in your editor. The language server should work correctly, providing completions, etc.
Open a module main.tf: Now, open the main.tf file inside your local module (e.g., ./modules/unit/main.tf). This is where the problem will appear. The language server will fail to load the schema, and you'll likely encounter the "schema not found" error.

By following these steps, you should be able to reliably reproduce the issue and confirm that the language server is not functioning correctly within your local modules. This helps you isolate the problem and focus on potential solutions.

Troubleshooting and Potential Solutions

Alright, now that we understand the problem and how to reproduce it, let's explore some potential solutions and workarounds. Unfortunately, as of the information provided, there isn't a perfect fix for this, but there are ways to mitigate the issue and improve your workflow. Keep in mind that the best solution might depend on your editor setup, OpenTofu version, and project structure.

1. Check your OpenTofu and Language Server Versions

Make sure you are using the latest stable versions of both OpenTofu and the language server. Bugs and compatibility issues are frequently addressed in updates. While this might not be a direct fix, it's a good first step.

OpenTofu: Ensure you're running a recent version of OpenTofu (e.g., 1.10.6 or later). Use tofu version to check.
Language Server: Update your language server. If you are using a Vim plugin like vim-tofu, ensure it's updated. Check your editor's plugin management for updates.

2. Verify OpenTofu Configuration

Double-check your main.tf and versions.tf files, particularly the provider definitions. Make sure:

The source and version attributes for your providers are correctly specified.
There are no typos or syntax errors in the provider configuration.
The provider versions are compatible with your OpenTofu version.

3. Editor/IDE Configuration

The way your editor or IDE interacts with tofu-ls can influence the issue. Here are some configuration aspects to check:

Root Directory: Ensure your editor is correctly identifying the root directory of your OpenTofu project. The language server uses this to locate the .terraform directory and provider plugins. For Vim users, this usually involves setting the cwd (current working directory) correctly.
Language Server Initialization: Make sure the language server is correctly initialized when opening files within local modules. Some editor plugins might have settings to control how the language server starts up.
Plugin Settings: Review your editor plugin settings for tofu-ls. Make sure that the plugin is configured to recognize and work with local modules. Some plugins have options related to project root detection or module support.

4. Workarounds and Manual Intervention

If the above steps don't resolve the issue, consider these workarounds:

Open Root main.tf First: Open the root main.tf file before opening module files. This can sometimes help the language server load the schemas correctly.
Reload the Language Server: Try reloading or restarting the language server after opening a module file. This can force it to re-index the project and pick up the necessary schemas.
Specify Provider Paths (Advanced): In some cases, you might be able to manually specify the paths to the provider plugins in your editor's configuration. This is a more advanced workaround and requires understanding your editor's and tofu-ls's settings.

5. Contribute to a Fix

If you're feeling ambitious, consider contributing to the tofu-ls project. The original report mentions that the reporter is interested in contributing a fix. If you are familiar with Go (the language tofu-ls is written in) and have time to spare, contributing a fix could be a huge benefit to the OpenTofu community. Look at the GitHub repository and see if you can help.

Conclusion

Dealing with the "schema not found" error in OpenTofu when working with local modules can be frustrating, but by understanding the underlying causes, checking your setup, and applying the workarounds, you can improve your workflow. Keep an eye on OpenTofu and language server updates, and consider contributing to the project if you have the skills. And remember, sometimes the best solution is a combination of adjustments and patience.

I hope this helps you, guys! Happy coding!

For further reading, you can visit the official OpenTofu documentation at OpenTofu Documentation.