googleapis/mcp-toolbox · error

source project and instance are required when restoring via

Error message

source project and instance are required when restoring via backup ID

What it means

RestoreBackup supports restoring either by numeric backup run ID or by a backup resource name. When a numeric backup ID is given, the API needs to know which project and instance originally hold that backup run; this library throws this error when either sourceProject or sourceInstance is empty in that case, because the RestoreBackupContext cannot be populated correctly.

Source

Thrown at internal/sources/cloudsqladmin/cloud_sql_admin.go:421

}

func (s *Source) RestoreBackup(ctx context.Context, targetProject, targetInstance, sourceProject, sourceInstance, backupID, accessToken string) (any, error) {
	request := &sqladmin.InstancesRestoreBackupRequest{}

	// There are 3 scenarios for the backup identifier:
	// 1. The identifier is an int64 containing the timestamp of the BackupRun.
	//    This is used to restore standard backups, and the RestoreBackupContext
	//    field should be populated with the backup ID and source instance info.
	// 2. The identifier is a string of the format
	//    'projects/{project-id}/locations/{location}/backupVaults/{backupvault}/dataSources/{datasource}/backups/{backup-uid}'.
	//    This is used to restore BackupDR backups, and the BackupdrBackup field
	//    should be populated.
	// 3. The identifer is a string of the format
	//    'projects/{project-id}/backups/{backup-uid}'. In this case, the Backup
	//    field should be populated.
	if backupRunID, err := strconv.ParseInt(backupID, 10, 64); err == nil {
		if sourceProject == "" || sourceInstance == "" {
			return nil, fmt.Errorf("source project and instance are required when restoring via backup ID")
		}
		request.RestoreBackupContext = &sqladmin.RestoreBackupContext{
			Project:     sourceProject,
			InstanceId:  sourceInstance,
			BackupRunId: backupRunID,
		}
	} else if backupDRRegex.MatchString(backupID) {
		request.BackupdrBackup = backupID
	} else {
		request.Backup = backupID
	}

	service, err := s.GetService(ctx, string(accessToken))
	if err != nil {
		return nil, err
	}

	resp, err := service.Instances.RestoreBackup(targetProject, targetInstance, request).Do()

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Pass both sourceProject and sourceInstance of the original backup when restoring via numeric backup ID
2. Alternatively, restore using the full backup resource name ('projects/{project}/backups/{backup-uid}') as backupID so source fields are not required
3. Check the tool configuration to ensure source_project and source_instance parameters are supplied

Example fix

// before
RestoreBackup(ctx, targetProject, targetInstance, "", "", "12345", token)
// after
RestoreBackup(ctx, targetProject, targetInstance, "source-project", "source-instance", "12345", token)

if backupIDMatchesInt64(backupID) {
    if sourceProject == "" || sourceInstance == "" {
        return errors.New("numeric backupID requires sourceProject and sourceInstance")
    }
}

func backupIDMatchesInt64(id string) bool {
    _, err := strconv.ParseInt(id, 10, 64)
    return err == nil
}

When it happens

Trigger: Calling RestoreBackup with backupID parseable as an int64 (e.g. "12345") while leaving sourceProject or sourceInstance as empty strings. Restoring by full backup resource name ('projects/{p}/backups/{uid}') does not trigger this check.

Common situations: Tool configs or invocations that pass only the backup ID and target instance, forgetting the source project/instance; programmatic callers that derive parameters from user input where optional source fields were dropped.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• missing 'password' parameter for non-IAM user
• error restoring backup: %w
• invalid connection name %q: project, region, and instance mu
• invalid region %q: must match %s
• invalid Cloud SQL instance ID %q: must match %s

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/22207497ab489773. Report an issue: GitHub.