{"record":{"id":"69117209567f5c11","repo":"hashicorp/terraform","slug":"top-level-block-deprecationmessage-must-not-be-se","errorCode":null,"errorMessage":"top-level block: DeprecationMessage must not be set when Deprecated is false","messagePattern":"top-level block: DeprecationMessage must not be set when Deprecated is false","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/configs/configschema/internal_validate.go","lineNumber":33,"sourceCode":"\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\n\t\t// all attributes within a computed block must also be computed\n\t\tif b.Computed && !attrS.Computed {\n\t\t\tmultiErr = errors.Join(multiErr, fmt.Errorf(\"%s%s: all attributes within computed blocks must also be computed\", prefix, name))\n\t\t}\n\t}\n\n\tfor name, blockS := range b.BlockTypes {\n\t\tif blockS == nil {\n\t\t\tmultiErr = errors.Join(multiErr, fmt.Errorf(\"%s%s: block schema is nil\", prefix, name))","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/configs/configschema/internal_validate.go#L15-L51","documentation":"During schema validation, the top-level Block has a non-empty DeprecationMessage but Deprecated is false. These two fields must be consistent: DeprecationMessage is only meaningful when Deprecated is true. This is a provider-developer error caught when the provider schema is loaded and validated by Terraform core.","triggerScenarios":"A provider schema defines DeprecationMessage on the root block without setting Deprecated: true. The internalValidate check at the top level (prefix == \"\") catches this inconsistency. Triggered during NewContext when provider schemas are loaded.","commonSituations":"A provider developer sets DeprecationMessage expecting it to work standalone, not realizing Deprecated must also be true. Copy-paste from a nested block where the combination was valid. Framework abstraction that auto-populates one field but not the other. Schema migration from terraform-plugin-sdk to terraform-plugin-framework where field semantics differ.","solutions":["If using terraform-plugin-framework, set both DeprecationMessage and the deprecated flag consistently in your schema definition.","If maintaining a custom schema struct, set b.Deprecated = true whenever b.DeprecationMessage != \"\".","Review the provider code for the resource/data source whose schema triggers this and fix the field combination."],"exampleFix":"// before — DeprecationMessage without Deprecated\n&configschema.Block{\n    DeprecationMessage: \"Use 'new_resource' instead\",\n    // Deprecated not set → defaults to false\n}\n\n// after — both set consistently\n&configschema.Block{\n    Deprecated:         true,\n    DeprecationMessage: \"Use 'new_resource' instead\",\n}","handlingStrategy":"validation","validationCode":"// Provider developers: validate deprecation field consistency\nfunc validateDeprecationFields(b *configschema.Block) error {\n    if !b.Deprecated && b.DeprecationMessage != \"\" {\n        return errors.New(\"DeprecationMessage set but Deprecated is false\")\n    }\n    return b.InternalValidate()\n}\n\n// Unit test gate:\nfunc TestSchemaDeprecationConsistency(t *testing.T) {\n    if err := myResourceSchema().InternalValidate(); err != nil {\n        t.Fatal(err)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set Deprecated: true when setting DeprecationMessage.","Add InternalValidate() to provider test suites as a CI gate.","When migrating schema frameworks, audit deprecation field semantics — they differ between SDK and framework."],"tags":["schema","validation","provider-development","deprecation","internal"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}