What causes "Agent model list is not found or empty" in mastra-ai/mastra?

Configure at least one model for the agent (in code: `new Agent({ model: ... })`, or via server model config routes) before reordering.

mastra-ai/mastra · error · HTTPException

Agent model list is not found or empty

Error message

Agent model list is not found or empty

What it means

Thrown by the model-reorder endpoint when `agent.getModelList()` returns null/undefined or an empty array. The reorder operation needs at least one model config to act on, so the server returns HTTP 400 'Agent model list is not found or empty'.

Source

Thrown at packages/server/src/server/handlers/agents.ts:3361

export const REORDER_AGENT_MODEL_LIST_ROUTE = createRoute({
  method: 'POST',
  path: '/agents/:agentId/models/reorder',
  responseType: 'json',
  pathParamSchema: agentIdPathParams,
  bodySchema: reorderAgentModelListBodySchema,
  responseSchema: modelManagementResponseSchema,
  summary: 'Reorder agent model list',
  description: 'Reorders the model list for agents with multiple model configurations',
  tags: ['Agents', 'Models'],
  requiresAuth: true,
  handler: async ({ mastra, agentId, reorderedModelIds }) => {
    try {
      const agent = await getAgentFromSystem({ mastra, agentId });

      const modelList = await agent.getModelList();
      if (!modelList || modelList.length === 0) {
        throw new HTTPException(400, { message: 'Agent model list is not found or empty' });
      }

      agent.reorderModels(reorderedModelIds);

      return { message: 'Model list reordered' };
    } catch (error) {
      return handleError(error, 'error reordering model list');
    }
  },
});

export const UPDATE_AGENT_MODEL_IN_MODEL_LIST_ROUTE = createRoute({
  method: 'POST',
  path: '/agents/:agentId/models/:modelConfigId',
  responseType: 'json',
  pathParamSchema: modelConfigIdPathParams,
  bodySchema: updateAgentModelInModelListBodySchema,
  responseSchema: modelManagementResponseSchema,

View on GitHub (pinned to 75dd419e61)

Solutions

Configure at least one model for the agent (in code: `new Agent({ model: ... })`, or via server model config routes) before reordering.
Check provider env vars/credentials so the default model resolves into the list.
If models are stored remotely, verify they exist and the mastra instance can load them.
Re-fetch the model list (GET route) to confirm the agent actually has models before retrying reorder.

Example fix

// before
await client.getAgent('my-agent').reorderModels(['m2', 'm1']); // agent has no models
// after
const agent = new Agent({ name: 'my-agent', model: 'openai/gpt-4o' });
await client.getAgent('my-agent').reorderModels(['m2', 'm1']);

Defensive patterns

Strategy: validation

Validate before calling

const models = await client.getAgent(agentId).getModels();
if (!models || models.length === 0) throw new Error(`Agent ${agentId} has no models configured; configure one before reordering`);

Type guard

function hasModels(models: Array<{ id: string }> | null | undefined): models is Array<{ id: string }> { return Array.isArray(models) && models.length > 0; }

Try / catch

try { await client.getAgent(agentId).reorderModels(ids); } catch (e) { if (is400(e, 'Agent model list is not found or empty')) { await configureDefaultModel(agentId); } else throw e; }

Prevention

Always set a `model` on agents in code or via server config before using model-management routes.
Verify provider credentials/env so default models resolve.
Fetch the model list before mutating it.
Watch for concurrent deletions of model configs in multi-user setups.

When it happens

Trigger: POSTing to the reorder-models route (`reorderedModelIds`) for an agent whose resolved model list is empty — e.g. agent has no models configured or model resolution fails/returns nothing.

Common situations: Agent created without any models; env vars for the model provider missing so the default model fails to resolve; agent pointing at a storage-backed model config that was deleted; multi-model setup cleared out by a bad update.

Related errors

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