What causes "backup init: '%s' must be set" in weaviate/weaviate?

Set BACKUP_GCS_BUCKET= in the Weaviate container's environment and restart.

backup init: '%s' must be set

Error message

backup init: '%s' must be set

What it means

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.

Source

Thrown at modules/backup-gcs/module.go:96

func (m *Module) Type() modulecapabilities.ModuleType {
	return modulecapabilities.Backup
}

func (m *Module) Init(ctx context.Context,
	params moduletools.ModuleInitParams,
) error {
	m.logger = params.GetLogger()
	m.dataPath = params.GetStorageProvider().DataPath()

	transport := params.GetConfig().BackupGCS
	config := &clientConfig{
		Bucket:          os.Getenv(gcsBucket),
		BackupPath:      os.Getenv(gcsPath),
		SkipAccessCheck: params.GetConfig().Backup.SkipAccessCheck,
		Transport:       transport,
	}
	if config.Bucket == "" {
		return errors.Errorf("backup init: '%s' must be set", gcsBucket)
	}

	client, err := newClient(ctx, config, m.dataPath, m.logger)
	if err != nil {
		return errors.Wrap(err, "init gcs client")
	}
	m.gcsClient = client

	exportConfig := &clientConfig{
		Bucket:          "", // export scheduler provides bucket via EXPORT_DEFAULT_BUCKET
		BackupPath:      "", // export scheduler provides path via EXPORT_DEFAULT_PATH
		SkipAccessCheck: params.GetConfig().Export.SkipAccessCheck,
		Transport:       transport,
	}
	exportClient, err := newClient(ctx, exportConfig, m.dataPath, m.logger)
	if err != nil {
		return errors.Wrap(err, "init gcs export client")
	}

View on GitHub (pinned to 75aa4b6d11)

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.

Example fix

// before (docker-compose)
environment:
  ENABLE_MODULES: backup-gcs
// after
environment:
  ENABLE_MODULES: backup-gcs
  BACKUP_GCS_BUCKET: my-weaviate-backups
  BACKUP_GCS_PATH: backups

Defensive patterns

Strategy: validation

Validate before calling

# shell — validate deployment config before starting Weaviate
if [ "$ENABLE_MODULES" = *"backup-gcs"* ] && [ -z "$BACKUP_GCS_BUCKET" ]; then
  echo "ERROR: backup-gcs enabled but BACKUP_GCS_BUCKET is not set" >&2
  exit 1
fi
// or in Go:
if strings.Contains(os.Getenv("ENABLE_MODULES"), "backup-gcs") && os.Getenv("BACKUP_GCS_BUCKET") == "" {
    return errors.New("backup-gcs enabled but BACKUP_GCS_BUCKET must be set")
}

Try / catch

// Weaviate fails fast at boot; catch at orchestration level (k8s initContainer / entrypoint):
if ! weaviate-ready; then
  if grep -q "must be set" <<<"$(weaviate --dry-run 2>&1)"; then
    echo "Fix: export BACKUP_GCS_BUCKET=<bucket> before starting"
  fi
fi

Prevention

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).

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/70023c26c80d9216. Report an issue: GitHub.