mastra-ai/mastra · error

Work item is required

Error message

Work item is required

What it means

requireWorkItemId is a shared guard used by the create/edit/delete work-item comment mutations in useWorkItemComments.ts. Since workItemId is `string | undefined`, it throws 'Work item is required' when a comment operation is attempted without a work item id. This prevents comment requests from targeting an invalid URL (queryKeys.workItemCommentsRoot(undefined)).

Source

Thrown at mastracode/factory-ui/src/hooks/useWorkItemComments.ts:28

  deleteWorkItemComment,
  editWorkItemComment,
  listWorkItemComments,
} from '../ui/domains/factory/services/comments';
import type { CreateWorkItemCommentInput, EditWorkItemCommentInput } from '../ui/domains/factory/services/comments';
import type { WorkItemComment, WorkItemCommentPage } from '../ui/domains/factory/services/commentsWire';

export interface WorkItemFeedScope {
  workItemId: string | undefined;
  factoryProjectId: string | undefined;
}

type CommentsData = InfiniteData<WorkItemCommentPage, string | undefined>;

/** Invalidation refetches every loaded page serially, so keep the window bounded. */
const MAX_COMMENT_PAGES = 5;

function requireWorkItemId(workItemId: string | undefined): string {
  if (!workItemId) throw new Error('Work item is required');
  return workItemId;
}

function createMutationKey(workItemId: string | undefined) {
  return [...queryKeys.workItemCommentsRoot(workItemId), 'create'] as const;
}

type CommentPatch = (comment: WorkItemComment) => WorkItemComment;

function patchPage(page: WorkItemCommentPage, commentId: string, patch: CommentPatch): WorkItemCommentPage {
  return {
    ...page,
    comments: page.comments.map(comment => (comment.id === commentId ? patch(comment) : comment)),
  };
}

/** Every anchor the work item is read under holds its own pages; all of them carry the row. */
function patchComments(queryClient: QueryClient, rootKey: QueryKey, commentId: string, patch: CommentPatch) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Render the comments panel (and its composer) only when workItemId is defined.
2. Clear/close the composer when the selected work item changes or is removed.
3. Check the call site passes the resolved work item id (not an optional chained value) into the hooks.

Example fix

// before
const { mutate: addComment } = useCreateWorkItemCommentMutation(workItemId);
<CommentBox onSubmit={text => addComment({ text })} />

// after
{workItemId ? <CommentBox onSubmit={text => addComment({ text })} /> : null}

if (!workItemId) return null; // don't render comments panel

const hasWorkItem = (id: string | undefined): id is string => typeof id === 'string' && id.length > 0;

addComment(payload, { onError: err => { if ((err as Error).message === 'Work item is required') closeComposer(); } });

When it happens

Trigger: Calling create/edit/delete comment mutations while workItemId is undefined — e.g. the comments panel mounted before the selected work item resolved, selection was cleared while the panel stayed open, or the id prop was dropped during refactoring.

Common situations: Submitting the comment box after clicking a different board item that deselected the current one; deep-linked page where the work item query hasn't resolved; optimistic UI keeping the composer open for a deleted work item.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Factory project is required
• Factory project is required
• Factory run requires a board work item
• Select a repository before starting a Factory run
• No Factory selected

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/a82d0c8a9c32d945. Report an issue: GitHub.