weaviate/weaviate · error

initialize S3 export client

Error message

initialize S3 export client

What it means

Wraps errors from constructing the separate S3 export client in Init. This client is built from EXPORT_* env vars (bucket, path, optional role ARN) and is distinct from the backup client, so it can fail even when backups are configured correctly.

Source

Thrown at modules/backup-s3/module.go:115

	// Create a separate export client with no default bucket or path.
	// The export scheduler supplies both via EXPORT_DEFAULT_BUCKET and
	// EXPORT_DEFAULT_PATH. When EXPORT_S3_ROLE_ARN is set the export
	// client additionally uses STS AssumeRole for cross-account access.
	exportCfg := newConfig(os.Getenv(s3Endpoint), "", "", useSSL)
	if exportRoleARN := os.Getenv(exportS3RoleARN); exportRoleARN != "" {
		exportCfg.RoleARN = exportRoleARN
		exportCfg.ExternalID = os.Getenv(exportS3ExternalID)
		exportCfg.STSEndpoint = os.Getenv(exportS3STSEndpoint)
		exportCfg.RoleSessionName = os.Getenv(exportS3RoleSessionName)
		if exportCfg.RoleSessionName == "" {
			exportCfg.RoleSessionName = "weaviate-export-s3"
		}
	}
	exportCfg.SkipAccessCheck = params.GetConfig().Export.SkipAccessCheck
	exportClient, err := newClient(exportCfg, m.logger, m.dataPath)
	if err != nil {
		return errors.Wrap(err, "initialize S3 export client")
	}
	m.exportClient = exportClient

	return nil
}

// ExportBackend returns the export-specific backend. It has no default
// bucket or path; the export scheduler supplies both via
// EXPORT_DEFAULT_BUCKET and EXPORT_DEFAULT_PATH.
func (m *Module) ExportBackend() modulecapabilities.BackupBackend {
	return &exportS3Backend{m.exportClient}
}

// exportS3Backend wraps an s3Client to satisfy the full BackupBackend
// interface (s3Client is missing IsExternal and Name).
type exportS3Backend struct {
	*s3Client
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Inspect the wrapped error for the AWS root cause (e.g. NoCredentialProviders, AccessDenied on AssumeRole)
2. Verify EXPORT_S3_ROLE_ARN is correct and the pod's identity is trusted by the role's trust policy
3. Set EXPORT_DEFAULT_BUCKET/EXPORT_DEFAULT_PATH to valid values or enable export skip access check
4. Test role assumption with aws sts assume-role from inside the container

if exportEnabled && os.Getenv("EXPORT_DEFAULT_BUCKET") == "" {
    return errors.New("export enabled but EXPORT_DEFAULT_BUCKET missing")
}
// verify role assumability out-of-band:
// aws sts assume-role --role-arn $EXPORT_S3_ROLE_ARN --role-session-name test

if err := m.Init(ctx, params); err != nil {
    if strings.Contains(err.Error(), "initialize S3 export client") {
        // disable export features, keep backup path alive
    }
}

When it happens

Trigger: EXPORT_S3_ROLE_ARN misconfigured/unassumable, invalid EXPORT_DEFAULT_BUCKET or endpoint, credential chain failing for the assumed role, or SkipAccessCheck=false and the export bucket not accessible.

Common situations: Export scheduler feature enabled with EXPORT_S3_ROLE_ARN pointing to a role the pod identity cannot assume; export bucket in a different region/account than backup bucket; missing EXPORT_DEFAULT_BUCKET.

Related errors

• initialize backend: %w
• failed to write export metadata: %w
• write metadata after %d attempts: %w
• initialize S3 backup module
• only root users can export db user credentials

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