gastownhall/beads · error

work item creation returned nil

Error message

work item creation returned nil

What it means

The workItemCreate mutation reported success (no errors array) but returned a nil workItem payload. This is a defensive invariant check in the client: a 'successful' mutation that yields no work item is a broken or edge-case API response, so the client refuses to fabricate a result.

Source

Thrown at internal/gitlab/client.go:630

			WorkItem *struct {
				ID     string `json:"id"`
				IID    string `json:"iid"`
				Title  string `json:"title"`
				WebURL string `json:"webUrl"`
				Type   struct {
					Name string `json:"name"`
				} `json:"workItemType"`
			} `json:"workItem"`
		} `json:"workItemCreate"`
	}
	if err := json.Unmarshal(data, &resp); err != nil {
		return nil, fmt.Errorf("failed to parse work item response: %w", err)
	}
	if len(resp.WorkItemCreate.Errors) > 0 {
		return nil, fmt.Errorf("work item creation failed: %s", resp.WorkItemCreate.Errors[0])
	}
	if resp.WorkItemCreate.WorkItem == nil {
		return nil, fmt.Errorf("work item creation returned nil")
	}

	wi := resp.WorkItemCreate.WorkItem
	return &WorkItem{
		ID:    wi.ID,
		IID:   wi.IID,
		Title: wi.Title,
		Type:  wi.Type.Name,
	}, nil
}

// GetWorkItemGID looks up the global ID of a work item by its project-scoped IID.
func (c *Client) GetWorkItemGID(ctx context.Context, projectPath string, iid int) (string, error) {
	query := fmt.Sprintf(`{
		project(fullPath: %q) {
			workItems(iid: "%d", first: 1) {
				nodes { id }
			}

View on GitHub (pinned to 71377f2769)

Solutions

1. Log the full raw GraphQL response to confirm workItem is truly null.
2. Upgrade or align the client with the GitLab version's stable workItemCreate schema.
3. Treat as a server-side anomaly and retry once; if persistent, report against the GitLab instance/version.
4. Check the instance's GraphQL schema via introspection to confirm the workItem field contract.

Example fix

null

// confirm the instance exposes a stable WorkItem type first
const q = `{ __type(name: "WorkItem") { fields { name } } }`

item, err := client.CreateTaskWorkItem(ctx, req)
if err != nil {
    if strings.Contains(err.Error(), "work item creation returned nil") {
        // possible transient instance anomaly; retry once, then report against the GitLab version
    }
    return err
}

When it happens

Trigger: Calling CreateTaskWorkItem against a GitLab instance where the mutation returns 200 with data present but workItem:null — schema drift, a partially rolled out feature, or an instance quirk where errors are reported out-of-band.

Common situations: Running against pre-release/beta GitLab builds where workItemCreate's success shape is unstable; schema drift after upgrades; a proxy stripping response fields while keeping status codes.

Related errors

• GraphQL request failed: %w
• failed to parse GraphQL response: %w
• GraphQL error: %s
• failed to parse work item response: %w
• work item creation failed: %s

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