{"record":{"id":"70023c26c80d9216","repo":"weaviate/weaviate","slug":"backup-init-s-must-be-set-70023c","errorCode":null,"errorMessage":"backup init: '%s' must be set","messagePattern":"backup init: '(.+?)' must be set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/backup-gcs/module.go","lineNumber":96,"sourceCode":"func (m *Module) Type() modulecapabilities.ModuleType {\n\treturn modulecapabilities.Backup\n}\n\nfunc (m *Module) Init(ctx context.Context,\n\tparams moduletools.ModuleInitParams,\n) error {\n\tm.logger = params.GetLogger()\n\tm.dataPath = params.GetStorageProvider().DataPath()\n\n\ttransport := params.GetConfig().BackupGCS\n\tconfig := &clientConfig{\n\t\tBucket:          os.Getenv(gcsBucket),\n\t\tBackupPath:      os.Getenv(gcsPath),\n\t\tSkipAccessCheck: params.GetConfig().Backup.SkipAccessCheck,\n\t\tTransport:       transport,\n\t}\n\tif config.Bucket == \"\" {\n\t\treturn errors.Errorf(\"backup init: '%s' must be set\", gcsBucket)\n\t}\n\n\tclient, err := newClient(ctx, config, m.dataPath, m.logger)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"init gcs client\")\n\t}\n\tm.gcsClient = client\n\n\texportConfig := &clientConfig{\n\t\tBucket:          \"\", // export scheduler provides bucket via EXPORT_DEFAULT_BUCKET\n\t\tBackupPath:      \"\", // export scheduler provides path via EXPORT_DEFAULT_PATH\n\t\tSkipAccessCheck: params.GetConfig().Export.SkipAccessCheck,\n\t\tTransport:       transport,\n\t}\n\texportClient, err := newClient(ctx, exportConfig, m.dataPath, m.logger)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"init gcs export client\")\n\t}","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/modules/backup-gcs/module.go#L78-L114","documentation":"The backup-gcs module requires a default backup bucket name at startup. It reads the environment variable BACKUP_GCS_BUCKET during Init and, when it is empty or unset, refuses to initialize with this error naming the missing variable. This is a deliberate fail-fast configuration validation so the module never starts in a state where backups cannot resolve a destination bucket.","triggerScenarios":"Starting Weaviate with the backup-gcs module enabled (ENABLE_MODULES=backup-gcs) while the BACKUP_GCS_BUCKET environment variable is unset or set to an empty string. Occurs during module Init at server boot, before the server accepts traffic.","commonSituations":"Missing env var in docker-compose / Kubernetes deployment manifests; var defined in the wrong scope (host shell vs container); typo like BACKUP_GCS_BUCket; migrating configs between versions where the var name changed; enabling the module without adding any GCS settings.","solutions":["Set BACKUP_GCS_BUCKET=<your-gcs-bucket-name> in the Weaviate container's environment and restart.","Confirm the variable is actually passed into the container (docker-compose environment: section, k8s env/envFrom, helm values).","If you only want module discovery without GCS backups, remove backup-gcs from ENABLE_MODULES instead of leaving it enabled unconfigured."],"exampleFix":"// before (docker-compose)\nenvironment:\n  ENABLE_MODULES: backup-gcs\n// after\nenvironment:\n  ENABLE_MODULES: backup-gcs\n  BACKUP_GCS_BUCKET: my-weaviate-backups\n  BACKUP_GCS_PATH: backups","handlingStrategy":"validation","validationCode":"# shell — validate deployment config before starting Weaviate\nif [ \"$ENABLE_MODULES\" = *\"backup-gcs\"* ] && [ -z \"$BACKUP_GCS_BUCKET\" ]; then\n  echo \"ERROR: backup-gcs enabled but BACKUP_GCS_BUCKET is not set\" >&2\n  exit 1\nfi\n// or in Go:\nif strings.Contains(os.Getenv(\"ENABLE_MODULES\"), \"backup-gcs\") && os.Getenv(\"BACKUP_GCS_BUCKET\") == \"\" {\n    return errors.New(\"backup-gcs enabled but BACKUP_GCS_BUCKET must be set\")\n}","typeGuard":null,"tryCatchPattern":"// Weaviate fails fast at boot; catch at orchestration level (k8s initContainer / entrypoint):\nif ! weaviate-ready; then\n  if grep -q \"must be set\" <<<\"$(weaviate --dry-run 2>&1)\"; then\n    echo \"Fix: export BACKUP_GCS_BUCKET=<bucket> before starting\"\n  fi\nfi","preventionTips":["Always pair ENABLE_MODULES entries with their required env vars in the same config block (compose, helm values, k8s manifest).","Use a config validation step in CI/CD (helm lint + values schema, docker-compose config check) that asserts BACKUP_GCS_BUCKET is non-empty when backup-gcs is enabled.","Avoid case-sensitive typos: the variable is exactly BACKUP_GCS_BUCKET.","Use envVar file/secrets templating that fails loudly on empty required values (e.g. ${BACKUP_GCS_BUCKET:?must be set} in compose)."],"tags":["gcs","backup","configuration","env-var","startup"],"backgroundTag":"missing-env-var","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}