hashicorp/terraform · error

Failed to negotiate acceptable chunk size. Expected size >…

Error message

Failed to negotiate acceptable chunk size. Expected size > 0 and <= %d bytes, provider wants %d bytes

What it means

Thrown by Pluggable.Configure after ConfigureStateStore when the provider's response Capabilities.ChunkSize is 0 or exceeds chunks.MaxStateStoreChunkSize (128 MiB). The core always requests chunks.DefaultStateStoreChunkSize (8 MiB); a provider may counter-propose a size, but it must be within (0, 128MB]. Zero indicates the provider never set the field.

Solutions

1. Upgrade the state-store provider to a release that correctly populates Capabilities.ChunkSize in ConfigureStateStore.
2. If you author the provider, set ChunkSize to a value in (0, 128MiB]; reuse chunks.DefaultStateStoreChunkSize unless you have a reason to change it.
3. Verify the provider and Terraform core are built from compatible SDK versions (check the chunks package constants they link).
4. If you cannot upgrade, switch to a built-in backend (local, s3, azurerm, etc.) until the provider is fixed.

Example fix

// provider side: ConfigureStateStore handler
// before
resp.Capabilities = providers.StateStoreClientCapabilities{}
// after
resp.Capabilities = providers.StateStoreClientCapabilities{
    ChunkSize: chunks.DefaultStateStoreChunkSize, // 8 MiB, within (0, 128 MiB]
}

// Provider side: validate before returning ConfigureStateStore.
const minChunk, maxChunk int64 = 1, chunks.MaxStateStoreChunkSize
if resp.Capabilities.ChunkSize < minChunk || resp.Capabilities.ChunkSize > maxChunk {
    resp.Capabilities.ChunkSize = chunks.DefaultStateStoreChunkSize // safe default
    resp.Diagnostics = resp.Diagnostics.Append(fmt.Errorf("provider returned invalid chunk size; using default"))
}

null

if diags := pluggable.Configure(cfg); diags.HasErrors() {
    if strings.Contains(diags.Err().Error(), "Failed to negotiate acceptable chunk size") {
        // provider bug: upgrade or switch backend
    }
    return diags
}

When it happens

Trigger: A state-store provider's ConfigureStateStore RPC returns resp.Capabilities.ChunkSize == 0 (struct left uninitialized) or a value > 128<<20. This happens with a buggy or version-mismatched third-party state store provider, or a provider built against an older chunks contract.

Common situations: Early/preview state-store providers that do not populate Capabilities; a provider compiled against a different revision of the providers.StateStoreClientCapabilities struct; a provider that intentionally tries to disable chunking by returning 0.

Related errors

• error when obtaining provider instance during state store…
• action schema not found for action
• attempted to encode a malformed backend state file…
• Failed obtain the in-use version of provider
• Failed to approve use of state storage provider

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/92cb03a65270a42b. Report an issue: GitHub.

Appendix: source

Thrown at internal/backend/pluggable/pluggable.go:129

	var diags tfdiags.Diagnostics
	req := providers.ConfigureStateStoreRequest{
		TypeName: p.typeName,
		Config:   config,
		Capabilities: providers.StateStoreClientCapabilities{
			// The core binary will always request the default chunk size from the provider to start
			ChunkSize: chunks.DefaultStateStoreChunkSize,
		},
	}
	resp := p.provider.ConfigureStateStore(req)
	diags = diags.Append(resp.Diagnostics)
	if diags.HasErrors() {
		return diags
	}

	// Validate the returned value from chunk size negotiation
	chunkSize := resp.Capabilities.ChunkSize
	if chunkSize == 0 || chunkSize > chunks.MaxStateStoreChunkSize {
		diags = diags.Append(fmt.Errorf("Failed to negotiate acceptable chunk size. "+
			"Expected size > 0 and <= %d bytes, provider wants %d bytes",
			chunks.MaxStateStoreChunkSize, chunkSize,
		))
		return diags
	}

	// Negotiated chunk size is valid, so set it in the provider server
	// that will use the value for future RPCs to read/write state.
	cs := p.provider.(providers.StateStoreChunkSizeSetter)
	cs.SetStateStoreChunkSize(p.typeName, int(chunkSize))
	log.Printf("[TRACE] Pluggable.Configure: negotiated a chunk size of %v when configuring state store %s",
		chunkSize,
		p.typeName,
	)

	return resp.Diagnostics
}

View on GitHub (pinned to d32a084675)