What causes "BecomeKey does not exist in keys[].Name" in semaphoreui/semaphore?

Add the missing access key to keys[] in the backup JSON.

BecomeKey does not exist in keys[].Name

Error message

BecomeKey does not exist in keys[].Name

What it means

BackupInventory.Verify also validates the optional BecomeKey reference: the named access key must exist in backup.keys[]. If getEntryByName finds no matching BackupAccessKey, verification returns this error, ensuring privilege-escalation key references resolve before restore.

Solutions

Add the missing access key to keys[] in the backup JSON.
Change become_key to reference an existing keys[].name entry.
Set become_key to null if privilege escalation is not required.
Re-export a full backup that includes both inventories and access keys.

Example fix

// before
"become_key": "sudo-key", "keys": [{"name": "deploy-key"}]
// after
"become_key": null  // or add sudo-key to keys[]

Defensive patterns

Strategy: validation

Validate before calling

func inventoryBecomeKeyExists(b BackupFormat) error {
    for _, inv := range b.Inventories {
        if inv.BecomeKey != nil && getEntryByName[BackupAccessKey](*inv.BecomeKey, b.Keys) == nil {
            return fmt.Errorf("inventory %q references missing become_key %q", inv.Name, *inv.BecomeKey)
        }
    }
    return nil
}

Try / catch

if err := backup.Verify(); err != nil {
    if strings.Contains(err.Error(), "BecomeKey does not exist") {
        // add the key or null the become_key reference, then retry
    }
    return err
}

Prevention

Keep become/privilege keys in every export containing inventories.
Clean up become_key references when rotating keys.
Run backup Verify as a preflight gate before restore operations.

When it happens

Trigger: Running backup Verify/restore preflight where inventory.become_key names an access key absent from keys[].name — key deleted/renamed at source, partial export, or manual edit.

Common situations: Sudo/become keys rotated and removed before backup; inventories referencing keys from a different project; backups filtered to exclude sensitive keys while inventories were kept.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of semaphoreui/semaphore@1774ccb71a (2026-09-07). Data as JSON: /api/errors/ee1bb2016c135def. Report an issue: GitHub.

Appendix: source

Thrown at services/project/restore.go:177

	newKey, err := b.store.CreateAccessKey(key)

	if err != nil {
		return err
	}
	b.keys = append(b.keys, newKey)
	return nil
}

func (e BackupInventory) Verify(backup *BackupFormat) error {
	if err := verifyDuplicate[BackupInventory](e.Name, backup.Inventories); err != nil {
		return err
	}
	if e.SSHKey != nil && getEntryByName[BackupAccessKey](e.SSHKey, backup.Keys) == nil {
		return fmt.Errorf("SSHKey does not exist in keys[].Name")
	}
	if e.BecomeKey != nil && getEntryByName[BackupAccessKey](e.BecomeKey, backup.Keys) == nil {
		return fmt.Errorf("BecomeKey does not exist in keys[].Name")
	}
	return nil
}

func (e BackupInventory) Restore(b *BackupDB) error {
	var SSHKeyID *int
	if e.SSHKey == nil {
		SSHKeyID = nil
	} else if k := findEntityByName[db.AccessKey](e.SSHKey, b.keys); k == nil {
		SSHKeyID = nil
	} else {
		SSHKeyID = &((*k).ID)
	}
	var BecomeKeyID *int
	if e.BecomeKey == nil {
		BecomeKeyID = nil
	} else if k := findEntityByName[db.AccessKey](e.BecomeKey, b.keys); k == nil {
		BecomeKeyID = nil

View on GitHub (pinned to 1774ccb71a)