mastra-ai/mastra · error · HTTPException

Failed to resolve created agent

Error message

Failed to resolve created agent

What it means

Internal error (HTTP 500) thrown immediately after creating a stored agent: the handler re-reads the record via `agentsStore.getByIdResolved(id, { status: 'published' })` and got null. Since the handler just created and (by default) published the agent, a null resolution means the created record or its published version isn't visible to the read path — an inconsistent storage state rather than a client mistake.

Source

Thrown at packages/server/src/server/handlers/stored-agents.ts:723

      // reliably determine it before saving — so the flag is overridden here.
      const isCodeSourceEditor = editor?.getSource?.() === 'code';
      const { versions } = await agentsStore.listVersions({ agentId: id, perPage: 1 });
      const initialVersion = versions[0];
      if (initialVersion && (autoPublish !== false || isCodeSourceEditor)) {
        await agentsStore.update({
          id,
          activeVersionId: initialVersion.id,
          status: 'published',
        });
      }
      editor?.agent.clearCache(id);

      // Return the resolved agent (thin record + version config). Published resolution falls
      // back to the latest version, so an unpublished code-agent override still returns the
      // config the caller just saved.
      const resolved = await agentsStore.getByIdResolved(id, { status: 'published' });
      if (!resolved) {
        throw new HTTPException(500, { message: 'Failed to resolve created agent' });
      }

      return enrichOrStripFavorites(mastra, requestContext, 'agent', resolved);
    } catch (error) {
      return handleError(error, 'Error creating stored agent');
    }
  },
});

/**
 * PATCH /stored/agents/:storedAgentId - Update a stored agent
 */
export const UPDATE_STORED_AGENT_ROUTE: ServerRoute<
  InferParams<typeof storedAgentIdPathParams, undefined, typeof updateStoredAgentBodySchema>,
  z.infer<typeof updateStoredAgentResponseSchema>,
  'json',
  RouteSchemas<
    typeof storedAgentIdPathParams,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use an up-to-date official storage adapter and run pending migrations so versions/agents tables are consistent
2. If staging a draft with autoPublish:false, fetch via draft status instead of assuming published resolution
3. Retry the read after create; if it persists, inspect the agents/versions rows to find the missing version record
4. If using a custom adapter, ensure getByIdResolved correctly joins the thin record with its versions

Example fix

// before
const resolved = await agentsStore.getByIdResolved(id, { status: 'published' }); // null when autoPublish=false

// after
const resolved =
  (await agentsStore.getByIdResolved(id, { status: 'published' })) ??
  (await agentsStore.getByIdResolved(id, { status: 'draft' }));

const created = await createStoredAgent(input);
const resolved = await getStoredAgent(created.id);
if (!resolved) console.warn('created agent not yet resolvable — check storage adapter/versioning');

function isResolvedAgent(a: unknown): a is { id: string; config: unknown } {
  return !!a && typeof a === 'object' && 'id' in a && 'config' in a;
}

try {
  return await createStoredAgent(input);
} catch (e) {
  if (isHttpError(e) && e.status === 500 && /Failed to resolve created agent/.test(e.message)) {
    await sleep(200);
    return getStoredAgent(input.id); // verify post-hoc
  }
  throw e;
}

When it happens

Trigger: Create-agent request where the record was written (create succeeded) but getByIdResolved with status 'published' returns nothing — e.g. autoPublish=false leaving only a draft, a storage adapter whose write isn't yet readable, or a corrupted/partial version write.

Common situations: Custom storage adapters with read-after-write inconsistencies; adapter versions where the versioning tables weren't migrated; calling create with autoPublish:false and then expecting published resolution; concurrent requests racing between create and resolve.

Related errors

• Failed to resolve updated agent
• Failed to resolve created skill
• AcpAgent does not support resuming suspended generate calls
• AcpAgent does not support resuming suspended stream calls
• ACP prompt stopped before completing: ${response.stopReason}

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