{"record":{"id":"205c37002e57ea4a","repo":"semaphoreui/semaphore","slug":"vault-key-does-not-exist-in-keys-name","errorCode":null,"errorMessage":"vault_key does not exist in keys[].name","messagePattern":"vault_key does not exist in keys\\[\\]\\.name","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"services/project/restore.go","lineNumber":257,"sourceCode":"\tb.repositories = append(b.repositories, newRepo)\n\treturn nil\n}\n\nfunc (e BackupTemplate) Verify(backup *BackupFormat) error {\n\tif err := verifyDuplicate[BackupTemplate](e.Name, backup.Templates); err != nil {\n\t\treturn err\n\t}\n\n\tif getEntryByName[BackupRepository](&e.Repository, backup.Repositories) == nil {\n\t\treturn fmt.Errorf(\"repository does not exist in repositories[].name\")\n\t}\n\n\tif e.Inventory != nil && getEntryByName[BackupInventory](e.Inventory, backup.Inventories) == nil {\n\t\treturn fmt.Errorf(\"inventory does not exist in inventories[].name\")\n\t}\n\n\tif e.VaultKey != nil && getEntryByName[BackupAccessKey](e.VaultKey, backup.Keys) == nil {\n\t\treturn fmt.Errorf(\"vault_key does not exist in keys[].name\")\n\t}\n\n\tif e.Vaults != nil {\n\t\tfor _, vault := range e.Vaults {\n\t\t\tif vault.VaultKey != nil {\n\t\t\t\tif getEntryByName[BackupAccessKey](vault.VaultKey, backup.Keys) == nil {\n\t\t\t\t\treturn fmt.Errorf(\"vaults[].vaultKey does not exist in keys[].name\")\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tif e.View != nil && getEntryByName[BackupView](e.View, backup.Views) == nil {\n\t\treturn fmt.Errorf(\"view does not exist in views[].name\")\n\t}\n\n\tif buildTemplate := getEntryByName[BackupTemplate](e.BuildTemplate, backup.Templates); string(e.Type) == \"deploy\" && buildTemplate == nil {\n\t\treturn fmt.Errorf(\"deploy is build but build_template does not exist in templates[].name\")","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/semaphoreui/semaphore/blob/1774ccb71a0a8b82eb74ea24c23ac9ab713de2fa/services/project/restore.go#L239-L275","documentation":"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.","triggerScenarios":"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.","commonSituations":"Exported backups that intentionally exclude secrets/keys; rotating or renaming vault keys between backup and restore; sharing backups between instances whose key sets differ.","solutions":["Include the access key with that name in backup.Keys.","Update the template's vaultKey to an existing keys[].name.","Null out vaultKey if the template should no longer use a vault key."],"exampleFix":"// before\n\"templates\": [{\"name\": \"build\", \"vaultKey\": \"secret-key\"}], \"keys\": []\n// after\n\"templates\": [{\"name\": \"build\", \"vaultKey\": \"secret-key\"}], \"keys\": [{\"name\": \"secret-key\"}]","handlingStrategy":"validation","validationCode":"if t.VaultKey != nil && !keyNameExists(*t.VaultKey, backup.Keys) {\n  return fmt.Errorf(\"template %q references missing vaultKey %q\", t.Name, *t.VaultKey)\n}","typeGuard":null,"tryCatchPattern":"if err := tmpl.Verify(backup); err != nil {\n  if strings.Contains(err.Error(), \"vault_key does not exist\") {\n    // re-export including keys, or remap the vault key\n  }\n}","preventionTips":["Do not strip secret keys from backups if templates reference them.","After rotating/renaming keys, take a fresh backup.","Prefer restoring into a project whose key names match the source."],"tags":["restore","backup","referential-integrity","vault","go"],"backgroundTag":"entity-not-found","analyzedSha":"1774ccb71a0a8b82eb74ea24c23ac9ab713de2fa","analyzedAt":"2026-09-07T11:00:33.293Z","contentChangedAt":"2026-09-07T11:00:33.293Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}