semaphoreui/semaphore · error

environment does not exist in environments[].name

Error message

environment does not exist in environments[].name

What it means

Thrown by BackupTemplate.Restore while resolving the template's Environments list: one of the referenced environment names has no match in b.environments, so the environment ID list cannot be built. Restore aborts for this template to avoid linking it to a nonexistent environment.

Solutions

1. Restore environments before templates so b.environments contains every referenced name.
2. Fix the environments[] names in the template entry to match the restored environments exactly.
3. Remove the missing environment from the template's environments list.
4. Re-run the full restore from the complete backup.

Example fix

// before
"environments": ["stg", "prod"], // backup only has "staging", "prod"
// after
"environments": ["staging", "prod"]

for _, env := range tmpl.Environments {
  if findEntityByName[db.Environment](&env, b.environments) == nil {
    return fmt.Errorf("environment %q not restored", env)
  }
}

if err := tmpl.Restore(b); err != nil {
  if strings.Contains(err.Error(), "environment does not exist") {
    // restore environments phase first, then retry the template
  }
}

When it happens

Trigger: Restore where any e.Environments[i] has findEntityByName[db.Environment](envName, b.environments) == nil — environments restored after templates, an environment removed post-Verify, or a name mismatch (case/whitespace) between the backup and the restored environments.

Common situations: Out-of-order partial restores; renaming environments between backup and restore; templates referencing environments from a different project's backup; retries of single-template restores without their environment dependencies.

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

• repository does not exist in repositories[].name
• inventory does not exist in inventories[].name
• vault_key does not exist in keys[].name
• vaults[].vaultKey does not exist in keys[].name
• view does not exist in views[].name

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

Appendix: source

Thrown at services/project/restore.go:297

}

func (e BackupTemplate) Restore(b *BackupDB) error {
	var InventoryID *int
	if e.Inventory != nil {
		if k := findEntityByName[db.Inventory](e.Inventory, b.inventories); k == nil {
			return fmt.Errorf("inventory does not exist in inventories[].name")
		} else {
			id := k.GetID()
			InventoryID = &id
		}
	}

	var EnvironmentIDs []int
	for i := range e.Environments {
		envName := &e.Environments[i]
		k := findEntityByName[db.Environment](envName, b.environments)
		if k == nil {
			return fmt.Errorf("environment does not exist in environments[].name")
		}
		EnvironmentIDs = append(EnvironmentIDs, k.GetID())
	}

	var RepositoryID int
	if k := findEntityByName[db.Repository](&e.Repository, b.repositories); k == nil {
		return fmt.Errorf("repository does not exist in repositories[].name")
	} else {
		RepositoryID = k.GetID()
	}

	var BuildTemplateID *int
	if string(e.Type) != "deploy" {
		BuildTemplateID = nil
	} else if k := findEntityByName[db.Template](e.BuildTemplate, b.templates); k == nil {
		BuildTemplateID = nil
	} else {
		BuildTemplateID = &(k.ID)

View on GitHub (pinned to 1774ccb71a)