mastra-ai/mastra · error · HTTPException

Invalid agent-builder action

Error message

Invalid agent-builder action: ${actionId}. Valid actions are: ${Object.keys(agentBuilderWorkflows).join(', ')}

What it means

The agent-builder 'get action' handler validates that the requested actionId is a registered agent-builder workflow via WorkflowRegistry.isAgentBuilderWorkflow. Unknown IDs raise HTTPException 400 listing all valid action IDs from the freshly registered workflow map.

Solutions

1. Use one of the listed valid action IDs from the error message
2. Upgrade/downgrade so client and server versions agree on available agent-builder actions
3. Check registerAgentBuilderWorkflows succeeded (no earlier registration errors in logs)
4. Correct typos in the actionId string sent by the client

Example fix

// before
GET /api/agent-builder/actions/get-agent-builder-action?actionId=runAgent
// after
GET /api/agent-builder/actions/get-agent-builder-action?actionId=<valid-action-from-list>

// Keep the client-side action list in sync before calling the endpoint
const VALID_ACTIONS = new Set(Object.keys(agentBuilderWorkflows));
function assertValidAction(actionId: string) {
  if (!VALID_ACTIONS.has(actionId)) {
    throw new Error(`Unknown agent-builder action: ${actionId}`);
  }
}

try {
  const res = await fetch(`/api/agent-builder/actions/get-agent-builder-action?actionId=${actionId}`);
  if (res.status === 400) {
    const body = await res.json();
    logger.warn('Invalid action, refreshing registry', { body });
    await refreshActionList();
    return;
  }
  return await res.json();
} catch (err) { logger.error(err); }

When it happens

Trigger: GET agent-builder action endpoint with an actionId that was never registered — e.g. a stale hardcoded ID in playground/client code, a typo, or the workflows failed to register (registerAgentBuilderWorkflows returned a set without that key).

Common situations: Client and server versions out of sync (client requests an action added in a newer server), renamed actions after a refactor, referencing a custom workflow that was never registered as an agent-builder workflow, or an environment where workflow registration partially failed.

Related errors

• Invalid agent-builder action
• Agent ID is required
• Argument " " is required
• bad request
• Both threadId or resourceId must be provided

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

Appendix: source

Thrown at packages/server/src/server/handlers/agent-builder.ts:92

export const GET_AGENT_BUILDER_ACTION_BY_ID_ROUTE = createRoute({
  method: 'GET',
  path: '/agent-builder/:actionId',
  responseType: 'json',
  pathParamSchema: actionIdPathParams,
  responseSchema: workflowInfoSchema,
  summary: 'Get action by ID',
  description: 'Returns details for a specific agent-builder action',
  tags: ['Agent Builder'],
  requiresAuth: true,
  handler: async ctx => {
    const { mastra, actionId } = ctx;
    const logger = mastra.getLogger();
    try {
      const agentBuilderWorkflows = await registerAgentBuilderWorkflows(mastra);

      if (actionId && !WorkflowRegistry.isAgentBuilderWorkflow(actionId)) {
        throw new HTTPException(400, {
          message: `Invalid agent-builder action: ${actionId}. Valid actions are: ${Object.keys(agentBuilderWorkflows).join(', ')}`,
        });
      }

      logger.info('Getting agent builder action by ID', { actionId });

      return await workflows.GET_WORKFLOW_BY_ID_ROUTE.handler({ ...ctx, workflowId: actionId });
    } catch (error) {
      logger.error('Error getting agent builder action by ID', { error, actionId });
      return handleError(error, 'Error getting agent builder action');
    } finally {
      WorkflowRegistry.cleanup();
    }
  },
});

export const LIST_AGENT_BUILDER_ACTION_RUNS_ROUTE = createRoute({
  method: 'GET',

View on GitHub (pinned to 75dd419e61)