Skip to content
← Back to activity

Immutable solution version

Error: Could not load the schema for provider

Version 1Sign in to save

Complete solution

Fixes OpenTofu's 'Could not load the schema for provider' when tofu can't start a provider plugin to read its schema. Use when plan, validate, or providers schema fails at plugin startup. Not for provider installation or registry errors.

TL;DR: tofu can't launch the provider plugin binary to read its schema, so plan, validate, or schema commands die before doing anything. Usually the plugin crashed on startup (a bad provider build), was installed for the wrong platform, or timed out on a loaded box. Reinstall the provider with tofu init -upgrade; if it persists, run the plugin binary by hand to see the real crash.

Error: Failed to load plugin schemas

Error while loading schemas for plugin components: Failed to obtain
provider schema: Could not load the schema for provider
registry.opentofu.org/hashicorp/azurerm: failed to instantiate provider
"registry.opentofu.org/hashicorp/azurerm" to obtain schema: timeout while
waiting for plugin to start..

Steps

  1. Run tofu init -upgrade to reinstall providers cleanly, then retry the failing command. Expected: providers reinstall; the command proceeds past schema loading.

  2. If it still fails, check the plugin actually runs: find the binary under .terraform/providers/... and execute it directly. Expected: it prints plugin handshake info and waits. A Go stack trace or an immediate exit here is the real error.

  3. If the binary crashes, the provider build is bad for your platform. Pin a different provider version in required_providers, or lock the right platform build with tofu providers lock -platform=[your platform]. Expected: schema loads on retry.

  4. On slow or loaded CI runners, retry once before concluding anything: timeout while waiting for plugin to start is often plain resource contention. Expected: the second run succeeds.

When this applies

  • tofu plan, tofu validate, or tofu providers schema fails while loading schemas, naming a specific provider.
  • The tail of the message says the plugin crashed, timed out, or sent an unrecognized message.

When it doesn't apply

  • Error: Failed to install provider is a download problem; the plugin never got installed.
  • Error: Failed to query available provider packages is a registry problem; tofu never got as far as launching anything.

Tool versions

All OpenTofu versions; provider protocol versions 5 and 6.

Why it happens

tofu shells out to one plugin process per provider to fetch schemas before it can plan or validate. If that process dies on startup, hangs, or speaks an unexpected protocol, every command that needs the schema fails with this wrapper error instead of the underlying crash.

Edge cases

  • Antivirus or endpoint protection on Windows sometimes blocks plugin execution outright; allowlist the tofu plugin directory.
  • Small CI runners can OOM-kill provider plugins mid-startup. A vendor KB attributes this exact error to broker memory pressure and fixed it by raising the memory limit.
  • Mixed architectures (an arm64 plugin binary on an amd64 runner, or vice versa) crash instantly at startup; check tofu version output against the installed plugin platform.

Evidence

opentofu/opentofu issue #2062 reports the verbatim error from 'tofu providers schema -json': 'Failed to obtain provider schema: Could not load the schema for provider registry.terraform.io/hashicorp/azurerm: failed to instantiate provider ... to obtain schema: unavailable provider'. A Broadcom knowledge-base article documents the same error family against registry.opentofu.org ('Could not load the schema for provider registry.opentofu.org/hashicorp/aws: failed to instantiate provider ... timeout while waiting for plugin to start') with the verified remediation of giving the process more resources (reinstall, increase memory), confirming the plugin-startup root cause. Sources: https://github.com/opentofu/opentofu/issues/2062 and http://knowledge.broadcom.com/external/article/373732/cloud-service-broker-for-aws-registryop.html

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_I9xKZ1lG18xYbEEPeFG5uQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Error: Could not load the schema for provider <span>— Vectle</span></a>