semaphoreui/semaphore · error

vault_key does not exist in keys[].name

Error message

vault_key does not exist in keys[].name

What it means

Thrown by BackupTemplate.Verify when the template's top-level VaultKey is set but no key with that name exists in backup.Keys. Vault keys are stored by name reference so secrets can be re-linked to the restored project's access keys.

Solutions

1. Include the access key with that name in backup.Keys.
2. Update the template's vaultKey to an existing keys[].name.
3. Null out vaultKey if the template should no longer use a vault key.

Example fix

// before
"templates": [{"name": "build", "vaultKey": "secret-key"}], "keys": []
// after
"templates": [{"name": "build", "vaultKey": "secret-key"}], "keys": [{"name": "secret-key"}]

if t.VaultKey != nil && !keyNameExists(*t.VaultKey, backup.Keys) {
  return fmt.Errorf("template %q references missing vaultKey %q", t.Name, *t.VaultKey)
}

if err := tmpl.Verify(backup); err != nil {
  if strings.Contains(err.Error(), "vault_key does not exist") {
    // re-export including keys, or remap the vault key
  }
}

When it happens

Trigger: Verify with e.VaultKey != nil and no BackupAccessKey of that name in backup.Keys — key dropped from export for security, renamed, or referenced with wrong casing.

Common situations: Exported backups that intentionally exclude secrets/keys; rotating or renaming vault keys between backup and restore; sharing backups between instances whose key sets differ.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• vaults[].vaultKey does not exist in keys[].name
• repository does not exist in repositories[].name
• inventory does not exist in inventories[].name
• view does not exist in views[].name
• deploy is build but build_template does not exist in…

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

Appendix: source

Thrown at services/project/restore.go:257

	b.repositories = append(b.repositories, newRepo)
	return nil
}

func (e BackupTemplate) Verify(backup *BackupFormat) error {
	if err := verifyDuplicate[BackupTemplate](e.Name, backup.Templates); err != nil {
		return err
	}

	if getEntryByName[BackupRepository](&e.Repository, backup.Repositories) == nil {
		return fmt.Errorf("repository does not exist in repositories[].name")
	}

	if e.Inventory != nil && getEntryByName[BackupInventory](e.Inventory, backup.Inventories) == nil {
		return fmt.Errorf("inventory does not exist in inventories[].name")
	}

	if e.VaultKey != nil && getEntryByName[BackupAccessKey](e.VaultKey, backup.Keys) == nil {
		return fmt.Errorf("vault_key does not exist in keys[].name")
	}

	if e.Vaults != nil {
		for _, vault := range e.Vaults {
			if vault.VaultKey != nil {
				if getEntryByName[BackupAccessKey](vault.VaultKey, backup.Keys) == nil {
					return fmt.Errorf("vaults[].vaultKey does not exist in keys[].name")
				}
			}
		}
	}

	if e.View != nil && getEntryByName[BackupView](e.View, backup.Views) == nil {
		return fmt.Errorf("view does not exist in views[].name")
	}

	if buildTemplate := getEntryByName[BackupTemplate](e.BuildTemplate, backup.Templates); string(e.Type) == "deploy" && buildTemplate == nil {
		return fmt.Errorf("deploy is build but build_template does not exist in templates[].name")

View on GitHub (pinned to 1774ccb71a)