{"record":{"id":"e5234efcf49dcda1","repo":"kopia/kopia","slug":"please-set-q-env-variable-to-use-this-feature","errorCode":null,"errorMessage":"please set %q env variable to use this feature","messagePattern":"please set %q env variable to use this feature","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command_repository_upgrade.go","lineNumber":54,"sourceCode":"\texperimentalWarning = `WARNING: The upgrade command is an EXPERIMENTAL feature. Please DO NOT use it, it may corrupt your repository and cause data loss.\n\nYou will need to set the env variable KOPIA_UPGRADE_LOCK_ENABLED in order to use this feature.\n`\n\tupgradeLockFeatureEnv         = \"KOPIA_UPGRADE_LOCK_ENABLED\"\n\tmaxPermittedClockDriftDefault = 5 * time.Minute\n)\n\nconst (\n\tcommitModeAlwaysCommit = \"always\"\n\tcommitModeNeverCommit  = \"never\"\n)\n\nfunc (c *commandRepositoryUpgrade) setup(svc advancedAppServices, parent commandParent) {\n\t// override the parent, the upgrade sub-command becomes the new parent here-onwards\n\tparent = parent.Command(\"upgrade\", \"Upgrade repository format.\\n\\n\"+warningColor.Sprint(experimentalWarning)).Hidden().\n\t\tValidate(func(_ *kingpin.CmdClause) error {\n\t\t\tif v := os.Getenv(c.svc.EnvName(upgradeLockFeatureEnv)); v == \"\" {\n\t\t\t\treturn errors.Errorf(\"please set %q env variable to use this feature\", upgradeLockFeatureEnv)\n\t\t\t}\n\n\t\t\treturn nil\n\t\t})\n\n\tbeginCmd := parent.Command(\"begin\", \"Begin upgrade.\")\n\tbeginCmd.Flag(\"io-drain-timeout\", \"Max time it should take all other Kopia clients to drop repository connections\").Default(format.DefaultRepositoryBlobCacheDuration.String()).DurationVar(&c.ioDrainTimeout)\n\tbeginCmd.Flag(\"allow-unsafe-upgrade\", \"Force using an unsafe io-drain-timeout for the upgrade lock\").Default(falseStr).Hidden().BoolVar(&c.allowUnsafeUpgradeTimings)\n\tbeginCmd.Flag(\"status-poll-interval\", \"An advisory polling interval to check for the status of upgrade\").Default(\"60s\").DurationVar(&c.statusPollInterval)\n\tbeginCmd.Flag(\"max-permitted-clock-drift\", \"The maximum drift between repository and client clocks\").Default(maxPermittedClockDriftDefault.String()).DurationVar(&c.maxPermittedClockDrift)\n\tbeginCmd.Flag(\"lock-only\", \"Advertise the upgrade lock and exit without actually performing the drain or upgrade\").Default(falseStr).Hidden().BoolVar(&c.lockOnly) // this is used by tests\n\tbeginCmd.Flag(\"commit-mode\", \"Change behavior of commit. When not set, commit on validation success. 'always': always commit. 'never': always exit before commit.\").Hidden().EnumVar(&c.commitMode, commitModeAlwaysCommit, commitModeNeverCommit)\n\n\t// upgrade phases\n\n\t// Set the upgrade lock intent.\n\tbeginCmd.Action(svc.directRepositoryWriteAction(c.runPhase(c.setLockIntent)))\n\t// If requested then drain all the clients otherwise stop here.","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/cli/command_repository_upgrade.go#L36-L72","documentation":"The `repository upgrade` sub-command is experimental and guarded: its kingpin Validate hook requires the environment variable named by upgradeLockFeatureEnv (KOPIA_ENABLE_EXPERIMENTAL_UPGRADE_LOCK) to be set to a non-empty value. Without it, the command refuses to run with this error.","triggerScenarios":"Invoking `kopia repository upgrade ...` (or its begin/resume sub-commands) when the upgrade-lock feature env variable is unset or empty.","commonSituations":"Operators upgrading a direct-write (filesystem/rclone) repository who are unaware the new upgrade flow is feature-gated; CI scripts that worked before the guard was introduced; env var set in the wrong shell/session or with an empty value.","solutions":["Set the required env variable before running: `export KOPIA_ENABLE_EXPERIMENTAL_UPGRADE_LOCK=on` (any non-empty value).","Re-run the upgrade command in the same shell/session so the variable is visible.","In CI, add the variable to the job's environment/secrets configuration.","Read the repository-upgrade docs to confirm the flow before enabling the experimental feature."],"exampleFix":"// before\nkopia repository upgrade begin ...\n// error: please set \"KOPIA_ENABLE_EXPERIMENTAL_UPGRADE_LOCK\" env variable to use this feature\n\n// after\nexport KOPIA_ENABLE_EXPERIMENTAL_UPGRADE_LOCK=on\nkopia repository upgrade begin ...","handlingStrategy":"validation","validationCode":"// fail fast in scripts if the experimental-upgrade gate is missing\nif os.Getenv(\"KOPIA_ENABLE_EXPERIMENTAL_UPGRADE_LOCK\") == \"\" {\n    return errors.New(\"repository upgrade requires KOPIA_ENABLE_EXPERIMENTAL_UPGRADE_LOCK to be set\")\n}","typeGuard":null,"tryCatchPattern":"if err := upgradeCmd.Run(); err != nil && strings.Contains(err.Error(), \"env variable to use this feature\") {\n    fmt.Fprintln(os.Stderr, \"export KOPIA_ENABLE_EXPERIMENTAL_UPGRADE_LOCK=on before running repository upgrade\")\n    os.Exit(1)\n}","preventionTips":["Export the env variable in the same shell/session (or CI job env) that runs the upgrade.","Document the experimental gate in runbooks for repository upgrades.","Verify with `echo $KOPIA_ENABLE_EXPERIMENTAL_UPGRADE_LOCK` before the upgrade step.","Read the upgrade documentation; the feature is intentionally hidden and gated."],"tags":["cli","environment-variable","repository-upgrade","experimental"],"backgroundTag":"missing-env-var","analyzedSha":"82495e54b584c1ef6073c9e1be048f57f8aef078","analyzedAt":"2026-09-07T20:35:21.689Z","contentChangedAt":"2026-09-07T20:35:21.689Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}