semaphoreui/semaphore · error

item does not exist

Error message

item %s does not exist

What it means

findNameBySlug in services/project/backup.go:19 does a linear scan of a list of backup entities, matching each one's GetSlug() against the requested slug. If no item matches, it returns "item %s does not exist". This is part of project backup/restore formatting, where backup JSON references entities by slug and the code maps a slug back to a human-readable name.

Solutions

1. Check the slug in the backup file against the existing entities (GET /inventory, /environment, /repository endpoints) and recreate the missing entity or fix the slug.
2. Re-export the backup including all referenced entities so slugs resolve.
3. Verify slug spelling and case in the backup JSON exactly matches the live entity's slug.
4. Delete or null out the stale slug reference in the backup JSON before restoring.

Example fix

// before (backup JSON references slug that does not exist)
{"repository_slug": "prod-repo"}
// after
# create the repository with slug "prod-repo" in the target project, or edit the backup:
{"repository_slug": "actual-repo-slug"}

slugs := map[string]bool{}
for _, it := range items { slugs[it.GetSlug()] = true }
if !slugs[slug] { return fmt.Errorf("backup references missing entity slug %q", slug) }

func slugExists(slug string, items []db.BackupSluggedEntity) bool {
    for _, it := range items {
        if it.GetSlug() == slug { return true }
    }
    return false
}

When it happens

Trigger: Calling format (project backup formatting) with a backup file that references an entity slug (e.g. a repository, environment, or inventory slug) that is not present in the current database's list of entities for that project.

Common situations: Restoring a backup into a different Semaphore instance where the referenced repository/environment/inventory was deleted or renamed; slug case mismatch (slugs are compared exactly); the backup was exported from a project whose related entities were not included in the export.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• item does not exist
• 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

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

Appendix: source

Thrown at services/project/backup.go:19

package project

import (
	"encoding/json"
	"fmt"
	"reflect"

	"github.com/semaphoreui/semaphore/db"
	"github.com/semaphoreui/semaphore/pkg/random"
)

func findNameBySlug[T db.BackupSluggedEntity](slug string, items []T) (*string, error) {
	for _, o := range items {
		if o.GetSlug() == slug {
			name := o.GetName()
			return &name, nil
		}
	}
	return nil, fmt.Errorf("item %s does not exist", slug)
}

func findNameByID[T db.BackupEntity](ID int, items []T) (*string, error) {
	for _, o := range items {
		if o.GetID() == ID {
			name := o.GetName()
			return &name, nil
		}
	}
	return nil, fmt.Errorf("item %d does not exist", ID)
}

func findEntityByName[T db.BackupEntity](name *string, items []T) *T {
	if name == nil {
		return nil
	}
	for _, o := range items {
		if o.GetName() == *name {

View on GitHub (pinned to 1774ccb71a)