paperclipai/paperclip · warning · RunnerGoalActionError

goal_action_unsupported

goal_action_unsupported

Error message

goal_action_unsupported: ${request.action} is unsupported by this agent session.

What it means

After loading the session's stored capability, `act` requires `capability.availability === 'available'` and that `capability.actions` includes the action implied by the request (set/edit/replace→set, pause→pause, resume→resume, clear→clear). Otherwise it throws `RunnerGoalActionError` with the capability's reasonCode, defaulting to `goal_action_unsupported`. The session exists but doesn't permit this specific goal operation.

Source

Thrown at server/src/services/runner-goals.ts:425

          repeated: true,
          session,
          status: existingAction.status,
          result: asRecord(existingAction.resultJson),
        };
      }
      if (session.goalRevision !== request.expectedRevision) {
        throw new RunnerGoalConflictError("stale_revision", currentProjection);
      }
      const capability = storedCapability(session, fallbackCapability);
      const requiredCapabilityAction = request.action === "pause"
        ? "pause"
        : request.action === "resume"
          ? "resume"
          : request.action === "clear"
            ? "clear"
            : "set";
      if (capability.availability !== "available" || !capability.actions.includes(requiredCapabilityAction)) {
        throw new RunnerGoalActionError(
          capability.reasonCode ?? "goal_action_unsupported",
          capability.reason ?? `${request.action} is unsupported by this agent session.`,
        );
      }
      if (request.tokenBudget != null && !capability.tokenBudgetControl) {
        throw new RunnerGoalActionError(
          "goal_token_budget_unsupported",
          "This agent session does not support goal token budgets.",
        );
      }
      if (request.action === "create" && currentGoal && currentGoal.status !== "complete") {
        throw new RunnerGoalConflictError("replacement_required", currentProjection);
      }
      if (["edit", "replace", "pause", "resume", "clear"].includes(request.action) && !currentGoal) {
        throw new RunnerGoalActionError("goal_not_found", "There is no current session goal.");
      }

      const nextRevision = session.goalRevision + 1;

View on GitHub (pinned to 01ad858492)

Solutions

1. Read the projection's `capability.actions` array and only send actions it includes
2. Surface only the supported goal controls in UI/tooling per session capability
3. Re-establish the session to re-negotiate full capability if actions are unexpectedly limited
4. Read `capability.reason`/`reasonCode` in the error to learn the adapter-specific cause

Example fix

// before
await act(companyId, issueId, { agentId, action: 'pause', ... });
// after
const proj = await projection(companyId, issueId, agentId);
if (!proj.capability.actions.includes('pause')) return; // pause not supported
await act(companyId, issueId, { agentId, action: 'pause', ... });

const proj = await runnerGoals.projection(companyId, issueId, agentId);
if (proj.capability.availability !== 'available' || !proj.capability.actions.includes(action)) {
  return { skipped: true, reason: proj.capability.reason ?? 'action unsupported' };
}

function actionSupported(proj, action) {
  return proj?.capability?.availability === 'available' && proj.capability.actions.includes(action);
}

try {
  await runnerGoals.act(companyId, issueId, req);
} catch (e) {
  if (e instanceof RunnerGoalActionError && e.code === 'goal_action_unsupported') {
    // hide/disable the control or fall back to supported actions
  } else throw e;
}

When it happens

Trigger: Calling pause/resume/clear on an agent whose capability.actions list only includes 'set'; calling any goal action on a session whose stored capability degraded to unavailable; adapter sessions that support goal setting but not pausing.

Common situations: Capability narrowed after session start (agent adapter negotiated fewer actions); UI offers all goal buttons regardless of capability; adapter version differences in supported actions; session capability probe failed and reasonCode defaults.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• session_goals_unsupported
• ${prefix}: the capability must be an object.
• goal_token_budget_unsupported
• runner_goal_stop_unsupported
• Adapter declares unsupported UI parser contract version — sk

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