gastownhall/beads · error

Failed to create issue for %s: %v

Error message

Failed to create issue for %s: %v

What it means

In doPull (internal/tracker/engine.go:552), when a pulled tracker issue has no local counterpart, beads calls e.Store.CreateIssue to import it. If storage rejects the create, the engine warns with the external identifier (e.g. GITLAB-42) and skips the issue — stats.Created is not incremented and no dependencies for it are recorded as created. This is per-issue and non-fatal to the rest of the pull.

Source

Thrown at internal/tracker/engine.go:552

				e.warn("Failed to update %s: %v", existing.ID, err)
				stats.Errors++
				if pulledIDs != nil {
					pulledIDs[existing.ID] = true
				}
				continue
			}
			stats.Updated++
			if pulledIDs != nil {
				pulledIDs[existing.ID] = true
			}
		} else {
			// Create new issue
			conv.Issue.ExternalRef = strPtr(ref)
			if raw, ok := marshalTrackerMetadata(extIssue.Metadata); ok {
				conv.Issue.Metadata = raw
			}
			if err := e.Store.CreateIssue(ctx, conv.Issue, e.Actor); err != nil {
				e.warn("Failed to create issue for %s: %v", extIssue.Identifier, err)
				continue
			}
			stats.Created++
			if pulledIDs != nil {
				pulledIDs[conv.Issue.ID] = true
			}
		}
	}

	// Create dependencies after all issues are imported
	depErrors := 0
	if opts.DryRun {
		depErrors = e.previewDependencies(ctx, pendingDeps, dryRunIssues)
	} else {
		depErrors = e.createDependencies(ctx, pendingDeps)
	}
	stats.Skipped += depErrors

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the `%v` detail to see whether it is an ID collision, constraint, or storage-level failure.
2. If it is an ID collision, resolve the duplicate (delete/rename the stale local issue or change the GenerateID hook configuration).
3. Fix the remote issue's data (missing title, invalid priority) that the mapper cannot sanitize.
4. Close other concurrent bd processes and retry the pull.
5. Run `bd doctor` / migrations if the storage schema may be stale, then re-pull.

Example fix

// before: re-imported issue collides with an existing local ID
Failed to create issue for GITLAB-42: issue bd-123 already exists
// after: remove the stale local duplicate, then
bd pull  # creates bd-123 fresh from GITLAB-42, stats.Created += 1

// before pulling, check for stale local IDs that could collide:
bd list --json | jq -r '.[].id' | sort | uniq -d
// ensure remote issue has required fields:
// title != "" and a valid priority before CreateIssue runs (mapper passes them through)

func createableIssue(i *types.Issue) bool {
    return i != nil && strings.TrimSpace(i.Title) != "" && strings.TrimSpace(i.ID) != ""
}

// creates are per-issue warnings, not returned errors; detect via stats and re-run:
stats, err := eng.Sync(ctx, opts)
if err != nil { log.Fatalf("sync: %v", err) }
// if expected creates are missing, grep stderr for 'Failed to create issue for' and resolve the named issues

When it happens

Trigger: Any pull/sync importing a new remote issue where CreateIssue fails — ID collision with an existing issue (the generated/remote ID already exists), constraint violation on required or invalid fields from the mapper (empty title, invalid priority/status), storage locked or unavailable, or metadata serialization producing invalid stored JSON.

Common situations: Hash-based ID generation colliding after repository history rewrites or issue deletion/re-creation; remote issues with malformed/empty fields the mapper passes through; concurrent bd processes on the same DB; version upgrades with unmigrated schema.

Related errors

• creating Linear milestone epic %q: %w
• database not available: %w
• searching local issues for Linear milestone %s: %w
• creating compound: %w
• cannot create %q: ID already exists in the %s table (issues

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