{"record":{"id":"bd20aa47fb617979","repo":"hashicorp/terraform","slug":"the-upgrade-flag-conflicts-with-lockfile-readonl","errorCode":null,"errorMessage":"The -upgrade flag conflicts with -lockfile=readonly.","messagePattern":"The -upgrade flag conflicts with -lockfile=readonly\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/arguments/init.go","lineNumber":220,"sourceCode":"\t\tdiags = diags.Append(tfdiags.Sourceless(\n\t\t\ttfdiags.Error,\n\t\t\t\"The -migrate-state and -json options are mutually-exclusive\",\n\t\t\t\"Terraform cannot ask for interactive approval when -json is set. To use the -migrate-state option, disable the -json option.\",\n\t\t))\n\t}\n\n\tif init.MigrateState && init.Reconfigure {\n\t\tdiags = diags.Append(tfdiags.Sourceless(\n\t\t\ttfdiags.Error,\n\t\t\t\"Invalid init options\",\n\t\t\t\"The -migrate-state and -reconfigure options are mutually-exclusive.\",\n\t\t))\n\t}\n\n\tif init.Upgrade && init.Lockfile == \"readonly\" {\n\t\t// This is appended as a Go error because this validation already existed this way\n\t\t// and it's been moved earlier in the process, to the arguments package.\n\t\tdiags = diags.Append(fmt.Errorf(\"The -upgrade flag conflicts with -lockfile=readonly.\"))\n\t}\n\n\targs := cmdFlags.Args()\n\tif len(args) != 0 {\n\t\t// No positional arguments are expected.\n\t\tdiags = diags.Append(tfdiags.Sourceless(\n\t\t\ttfdiags.Error,\n\t\t\t\"No positional arguments are expected\",\n\t\t\t\"The init command does not expect any positional arguments. Did you mean to use -chdir?\",\n\t\t))\n\t}\n\n\tbackendFlagSet := FlagIsSet(cmdFlags, \"backend\")\n\tcloudFlagSet := FlagIsSet(cmdFlags, \"cloud\")\n\n\tif backendFlagSet && cloudFlagSet {\n\t\tdiags = diags.Append(tfdiags.Sourceless(\n\t\t\ttfdiags.Error,","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/command/arguments/init.go#L202-L238","documentation":"Thrown by terraform init when both -upgrade and -lockfile=readonly are specified simultaneously. These flags are mutually exclusive because -upgrade fetches newer provider versions (which requires modifying the dependency lock file) while -lockfile=readonly forbids any lock file changes. The check runs in the arguments package before any init work begins.","triggerScenarios":"Running terraform init -upgrade -lockfile=readonly. The arguments package detects init.Upgrade==true and init.Lockfile==\"readonly\" and appends this error to diagnostics.","commonSituations":"Copy-pasting a CI pipeline command that includes both flags; misunderstanding that upgrading providers inherently requires writing to the lock file; attempting to enforce lock file immutability while also wanting provider upgrades.","solutions":["Remove -lockfile=readonly if you need to upgrade providers","Remove -upgrade if you need a read-only lock file","Split into two pipeline stages: first run init -upgrade to update providers and lock file, then subsequent runs can use -lockfile=readonly"],"exampleFix":"# before\nterraform init -upgrade -lockfile=readonly\n\n# after (choose one depending on intent)\nterraform init -upgrade\n# or\nterraform init -lockfile=readonly","handlingStrategy":"validation","validationCode":"// Validate init flags before invoking terraform init\nfunc validateInitFlags(upgrade bool, lockfile string) error {\n    if upgrade && lockfile == \"readonly\" {\n        return errors.New(\"-upgrade conflicts with -lockfile=readonly: \" +\n            \"upgrading providers requires writing to the lock file\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never combine -upgrade with -lockfile=readonly in the same init command","In CI pipelines, separate upgrade runs (which write the lock file) from verification runs (which use readonly)","Document which init command variant each pipeline stage uses","Add a pre-flight flag check in wrapper scripts"],"tags":["terraform-init","cli-flags","validation","lockfile","mutually-exclusive"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}