{"record":{"id":"dfd1bcfe8dbac7fd","repo":"hashicorp/terraform","slug":"top-level-block-schema-is-nil","errorCode":null,"errorMessage":"top-level block schema is nil","messagePattern":"top-level block schema is nil","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/configs/configschema/internal_validate.go","lineNumber":24,"sourceCode":"import (\n\t\"errors\"\n\t\"fmt\"\n\t\"regexp\"\n\n\t\"github.com/zclconf/go-cty/cty\"\n)\n\nvar validName = regexp.MustCompile(`^[a-z0-9_]+$`)\n\n// InternalValidate returns an error if the receiving block and its child schema\n// definitions have any inconsistencies with the documented rules for valid\n// schema.\n//\n// This can be used within unit tests to detect when a given schema is invalid,\n// and is run when terraform loads provider schemas during NewContext.\nfunc (b *Block) InternalValidate() error {\n\tif b == nil {\n\t\treturn fmt.Errorf(\"top-level block schema is nil\")\n\t}\n\treturn b.internalValidate(\"\")\n}\n\nfunc (b *Block) internalValidate(prefix string) error {\n\tvar multiErr error\n\n\tif prefix == \"\" && !b.Deprecated && b.DeprecationMessage != \"\" {\n\t\tmultiErr = errors.Join(multiErr, fmt.Errorf(\"top-level block: DeprecationMessage must not be set when Deprecated is false\"))\n\t}\n\n\tfor name, attrS := range b.Attributes {\n\t\tif attrS == nil {\n\t\t\tmultiErr = errors.Join(multiErr, fmt.Errorf(\"%s%s: attribute schema is nil\", prefix, name))\n\t\t\tcontinue\n\t\t}\n\t\tmultiErr = errors.Join(multiErr, attrS.internalValidate(name, prefix))\n","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/configs/configschema/internal_validate.go#L6-L42","documentation":"Block.InternalValidate() is called on a nil *Block pointer. This is a development-time validation that runs when Terraform loads provider schemas during NewContext. A nil top-level schema block indicates a provider returned a nil schema or the schema was not properly initialized before validation. This error is seen by provider developers or due to internal Terraform bugs, not by end users writing HCL.","triggerScenarios":"InternalValidate() is invoked on a Block that is nil. This happens when a provider plugin returns a nil schema for a resource/data source, or when Terraform's schema aggregation code passes a nil pointer into validation. Triggered during context creation (NewContext) when schemas are loaded.","commonSituations":"A provider plugin has a bug returning nil from its Schema() method. A custom Terraform fork or internal tooling constructs a schema tree with a nil root. A provider uses the terraform-plugin-sdk/terraform-plugin-framework incorrectly, leaving a schema unset. Rare Terraform core bug in schema aggregation.","solutions":["If you are a provider developer, ensure every resource and data source returns a non-nil schema.","Update the provider plugin to the latest version — this may be a known bug fixed in a newer release.","File an issue with the provider repository, including the resource type that triggers the error.","If using terraform-plugin-framework, verify all schema definitions are complete and non-nil."],"exampleFix":"// before (provider code) — nil schema returned\nfunc (r *resource) Schema(ctx context.Context, req schema.Request) (schema.Response, error) {\n    return schema.Response{}, nil  // nil schema\n}\n\n// after — return a complete schema\nfunc (r *resource) Schema(ctx context.Context, req schema.Request) (schema.Response, error) {\n    return schema.Response{\n        Schema: schema.Schema{\n            Attributes: map[string]schema.Attribute{...},\n        },\n    }, nil\n}","handlingStrategy":"validation","validationCode":"// Provider developers: call InternalValidate in unit tests\nfunc TestResourceSchemaValid(t *testing.T) {\n    schema := myResource().Schema(ctx)\n    block := schemaBlockFromFramework(schema) // convert to *configschema.Block\n    if err := block.InternalValidate(); err != nil {\n        t.Fatalf(\"schema invalid: %v\", err)\n    }\n}\n\n// Guard against nil before calling:\nif block == nil {\n    return errors.New(\"schema is nil — provider returned no schema\")\n}","typeGuard":"func isNonNilBlock(b *configschema.Block) bool {\n    return b != nil\n}","tryCatchPattern":null,"preventionTips":["Always return a fully populated schema from every resource and data source.","Add InternalValidate() calls to provider unit tests as a CI gate.","When using terraform-plugin-framework, ensure Schema() always returns a complete schema.Schema.","Never pass nil schema pointers through Terraform's schema pipeline."],"tags":["schema","validation","provider-development","nil-pointer","internal"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}