What causes "Select an agent to use /goal." in paperclipai/paperclip?

Select/assign an agent for the runner session, then retry the goal action.

Select an agent to use /goal.

Error message

Select an agent to use /goal.

What it means

useRunnerGoalControl's action handler refetches the runner goal capability query and throws when the current runner has no agentId, falling back to "Select an agent to use /goal." when the backend did not provide a capability.reason. It guards the /goal feature: goals require a runner session with an assigned agent.

Source

Thrown at ui/src/components/task-chat/RunnerGoalWidget.tsx:98

    if (next.issueId !== issueId || (agentId && next.agentId !== agentId)) return;
    const current = queryClient.getQueryData<RunnerGoalProjection>(key);
    if (current && next.revision > current.revision + 1) {
      void query.refetch();
      return;
    }
    if (!current || next.revision >= current.revision) queryClient.setQueryData(key, next);
  });

  const executeAction = useCallback(async (
    action: RunnerGoalAction,
    objective?: string,
    confirmReplace = false,
    expectedRevision?: number,
  ) => {
    setActionError(null);
    try {
      const current = query.data ?? (await query.refetch()).data;
      if (!current?.agentId) throw new Error(current?.capability.reason ?? "Select an agent to use /goal.");
      if (current.capability.availability !== "available") {
        throw new Error(current.capability.reason ?? "Session goals are unsupported by this agent.");
      }
      await mutation.mutateAsync({
        requestId: requestId(),
        agentId: current.agentId,
        expectedRevision: expectedRevision ?? current.revision,
        action,
        ...(objective ? { objective } : {}),
        ...(action === "replace" ? { confirmReplace } : {}),
      });
    } catch (error) {
      setActionError(error instanceof Error ? error.message : "The goal action could not be applied.");
      throw error;
    }
  }, [mutation, query]);

  const edit = useCallback(async () => {

View on GitHub (pinned to 01ad858492)

Solutions

Select/assign an agent for the runner session, then retry the goal action.
If the runner is stopped, restart it so an agent is attached.
Refresh the widget to refetch capability data if an agent is in fact assigned.
Check backend capability reason surfaced in the UI for the underlying cause when present.

Example fix

// before: acting without an assigned agent
await runnerGoal.control({ action: "set", goal });

// after: pre-check before acting
const cap = await runnerGoal.refetch();
if (!cap.data?.agentId) {
  showToast("Select an agent before setting a goal.");
  return;
}
await runnerGoal.control({ action: "set", goal });

Defensive patterns

Strategy: validation

Validate before calling

const cap = useRunnerGoalCapabilityQuery(runnerId).data;
const canSetGoal = Boolean(cap?.agentId);
if (!canSetGoal) disableGoalWidget("Select an agent to use /goal.");

Type guard

const hasAgent = (cap: { agentId?: string | null } | undefined): cap is { agentId: string } =>
  typeof cap?.agentId === "string" && cap.agentId.length > 0;

Try / catch

try {
  await runnerGoal.control({ action, goal });
} catch (e) {
  if (e instanceof Error && e.message === "Select an agent to use /goal.") {
    promptAgentSelection();
  } else throw e;
}

Prevention

Only render the goal widget after an agent is assigned to the runner.
Check capability.agentId before issuing goal actions.
Refetch capability data after session changes (restart, agent switch).

When it happens

Trigger: Invoking a goal action (set/clear via runnerGoal.control or the widget) while the runner-goal capability query returns data with agentId null/undefined and no explanatory capability.reason — e.g. no agent selected for the runner yet.

Common situations: User opens the goal widget before picking an agent for the run; agent was unassigned/stopped between widget load and action; stale capability data after a session restart; first load where refetch also returns no agent.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/58e7fdd1cdfc23e2. Report an issue: GitHub.