semaphoreui/semaphore · error

vaults[].vaultKey does not exist in keys[].name

Error message

vaults[].vaultKey does not exist in keys[].name

What it means

Thrown by BackupTemplate.Verify while iterating e.Vaults: a per-vault VaultKey name is not found in backup.Keys. This is the nested counterpart of the top-level vault_key check — each vault entry's key reference is validated individually.

Solutions

1. Add every key name referenced by vaults[].vaultKey to backup.Keys.
2. Fix the vault entry's vaultKey to match an existing keys[].name.
3. Remove the offending vault entry or its key reference.

Example fix

// before
"vaults": [{"vaultKey": "old-name"}], "keys": [{"name": "new-name"}]
// after
"vaults": [{"vaultKey": "new-name"}], "keys": [{"name": "new-name"}]

for _, v := range t.Vaults {
  if v.VaultKey != nil && !keyNameExists(*v.VaultKey, backup.Keys) {
    return fmt.Errorf("vault references missing key %q", *v.VaultKey)
  }
}

if err := tmpl.Verify(backup); err != nil {
  if strings.Contains(err.Error(), "vaults[].vaultKey does not exist") {
    // add the missing key or fix the vault entry
  }
}

When it happens

Trigger: Verify where any element of e.Vaults has VaultKey != nil with no matching BackupAccessKey in backup.Keys — typically only some vaults' keys made it into the export.

Common situations: Backups with partially exported key sets; vault entries copied from another project referencing keys that were not copied along; renaming keys after export.

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

• vault_key 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/5028144d0d2bb226. Report an issue: GitHub.

Appendix: source

Thrown at services/project/restore.go:264

	}

	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")
	}

	return nil
}

func (e BackupTemplate) Restore(b *BackupDB) error {
	var InventoryID *int

View on GitHub (pinned to 1774ccb71a)