failed to generate unique ID for issue '%s' after trying len

Error message

failed to generate unique ID for issue '%s' after trying lengths %d-%d with 10 nonces each

What it means

GenerateIssueIDs exhaustively tries hash-derived candidate IDs (lengths baseLength..maxLength, 10 nonces each) and returns this error when every candidate collides with an already-used ID. With up to 60 candidates per issue this practically means an ID-space exhaustion or a pathological duplicate-input situation, not a random clash.

Source

Thrown at internal/linear/mapping.go:119

					issue.Title,
					issue.Description,
					creator,
					issue.CreatedAt,
					length,
					nonce,
				)

				if !usedIDs[candidate] {
					issue.ID = candidate
					usedIDs[candidate] = true
					generated = true
					break
				}
			}
		}

		if !generated {
			return fmt.Errorf("failed to generate unique ID for issue '%s' after trying lengths %d-%d with 10 nonces each",
				issue.Title, baseLength, maxLength)
		}
	}

	return nil
}

// MappingConfig holds configurable mappings between Linear and Beads.
// All maps use lowercase keys for case-insensitive matching.
type MappingConfig struct {
	// PriorityMap maps Linear priority (0-4) to Beads priority (0-4).
	// Key is Linear priority as string, value is Beads priority.
	PriorityMap map[string]int

	// StateMap maps Linear state types/names to Beads statuses.
	// Key is lowercase state type or name, value is Beads status string.
	StateMap map[string]string

View on GitHub (pinned to 71377f2769)

Solutions

Check that issues have distinct and correct CreatedAt/timestamps (a common cause is all-zero CreatedAt).
Increase baseLength/maxLength to enlarge the candidate ID space.
Ensure existing IDs are recorded correctly in usedIDs and that previously generated IDs are persisted between runs.
Verify you are not re-importing duplicates of the same issue content.
Report upstream if it persists with distinct inputs — 60 collisions in a row indicates a hash or usedIDs bug.

Example fix

// before
issues := loadIssues() // CreatedAt zero-value for all issues
err := linear.GenerateIssueIDs(issues, "bd-", 3, 8)
// after
for i := range issues {
	if issues[i].CreatedAt.IsZero() {
		issues[i].CreatedAt = time.Now().UTC() // ensure unique hash input
	}
}
err := linear.GenerateIssueIDs(issues, "bd-", 3, 8)

Defensive patterns

Strategy: validation

Validate before calling

func validateIDInputs(issues []Issue) error {
	seenCreated := map[string]bool{}
	for _, is := range issues {
		if is.CreatedAt.IsZero() {
			return fmt.Errorf("issue %q has zero CreatedAt; fix timestamps before ID generation", is.Title)
		}
		key := is.Title + "|" + is.Description + "|" + is.CreatedAt.String()
		if seenCreated[key] {
			return fmt.Errorf("duplicate issue content for %q", is.Title)
		}
		seenCreated[key] = true
	}
	return nil
}

Try / catch

if err := linear.GenerateIssueIDs(issues, prefix, 3, 8); err != nil {
	return fmt.Errorf("ID generation failed (check for duplicate inputs or zero timestamps): %w", err)
}

Prevention

Ensure CreatedAt is set and unique per issue before generation.
Persist generated IDs so later runs don't re-generate and collide.
Avoid importing the same dataset twice without deduplication.
Use a baseLength that scales with your issue count (larger space for big sets).
Add a unit test with production-scale issue sets to catch exhaustion early.

When it happens

Trigger: Calling GenerateIssueIDs on an issue set where every hash candidate for an issue (deterministic function of prefix, title, description, creator, createdAt, length, nonce) is already present in usedIDs.

Common situations: Importing the same dataset repeatedly with identical title/description/creator/createdAt so the same candidate set is produced; a very short baseLength with a large existing issue set; a bug freezing issue.CreatedAt (zero timestamps) making all candidates identical across issues.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/2e214f87b33869db. Report an issue: GitHub.