mastra-ai/mastra · error · HTTPException

Invalid agent-builder action: ${actionId}. Valid actions are

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.

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)

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: ${actionId}
• bad request: ${responseText}
• Cannot delete the active version. Activate a different versi
• Agent ID is required
• 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.