CherryHQ/cherry-studio · error · Error

Agent not found: ${agentId}

Error message

Agent not found: ${agentId}

What it means

Thrown by runAgentTask when agentService.getAgent(agentId) returns null/falsy before dispatching the job. The job (schedule-fired or ad-hoc) references an agentId that no longer resolves to a stored agent — typically because the agent was deleted after the job was enqueued/scheduled but before it ran.

Source

Thrown at src/main/ai/agents/runAgentTask.ts:155

      workspace
    })
  }
  return session
}

export async function runAgentTask(ctx: JobContext<AgentTaskInput>): Promise<AgentTaskOutput> {
  const { agentId, prompt, timeoutMinutes, workspace } = ctx.input

  // schedule-fired jobs carry `scheduleId` on the row; manual ad-hoc enqueues
  // (no schedule) degrade gracefully: skip channel notification.
  const jobSnapshot = jobService.getById(ctx.jobId)
  const scheduleId = jobSnapshot?.scheduleId ?? null
  const scheduleSnapshot = scheduleId ? jobScheduleService.getById(scheduleId) : null
  const taskName = scheduleSnapshot?.name ?? null

  const agent = agentService.getAgent(agentId)
  if (!agent) {
    throw new Error(`Agent not found: ${agentId}`)
  }

  const config = agent.configuration ?? {}

  const isHeartbeat = taskName === HEARTBEAT_TASK_NAME && prompt === HEARTBEAT_PROMPT_SENTINEL

  let effectivePrompt = prompt

  if (isHeartbeat) {
    if (config.heartbeat_enabled === false) {
      logger.debug('Heartbeat skipped (disabled)', { agentId, scheduleId })
      return { sessionId: null, result: 'Skipped (disabled)' }
    }
    switch (workspace.type) {
      case AGENT_WORKSPACE_TYPE.SYSTEM:
        logger.debug('Heartbeat skipped (no file)', { agentId, scheduleId })
        return { sessionId: null, result: 'Skipped (no file)' }
      case AGENT_WORKSPACE_TYPE.USER:

View on GitHub (pinned to 726446b54c)

Solutions

1. Verify the agentId exists: `agentService.getAgent(agentId)` — if it is gone, the schedule is stale.
2. When an agent is deleted, also delete/disable its job schedules and cancel in-flight jobs (see jobScheduleService / jobService).
3. If the agent should exist, check why getAgent returns null (provisioning failure, DB row missing).
4. Catch the error at the job layer and mark the schedule inactive so it does not keep firing.

Example fix

// before: agent deleted but schedule still fires
const agent = agentService.getAgent(agentId)
if (!agent) throw new Error(`Agent not found: ${agentId}`)

// after: on agent delete, tear down its schedules
await jobScheduleService.cancelSchedulesForAgent(agentId)
await jobService.cancelJobsForAgent(agentId)
await agentService.delete(agentId)

const agent = agentService.getAgent(agentId)
if (!agent) {
  // cancel stale schedule/job instead of letting runAgentTask throw
  await jobScheduleService.cancelSchedulesForAgent(agentId).catch(() => {})
  await jobService.cancelJobsForAgent(agentId).catch(() => {})
  return
}

function agentExists(a: unknown): a is { id: string; configuration: Record<string, unknown> } {
  return a != null && typeof (a as { id?: unknown }).id === 'string'
}

try {
  return await runAgentTask(ctx)
} catch (e) {
  if (e instanceof Error && /Agent not found:/.test(e.message)) {
    // mark the owning schedule inactive so it stops firing
    await jobScheduleService.deactivate(scheduleId).catch(() => {})
    return { sessionId: null, result: 'Skipped (agent deleted)' }
  } else throw e
}

When it happens

Trigger: A scheduled or manually-enqueued agent task executes (runAgentTask) for an agentId that agentService.getAgent cannot find.

Common situations: The user deleted the agent while its heartbeat/ad-hoc schedule was still active; a schedule was imported pointing at a non-existent agent; agentId mismatch between the job row and the agents table; the agent failed to provision/create.

Related errors

• Heartbeat workspace must be user-owned: ${workspace.workspac
• Agent session ${session.id} became invalid while starting ta
• Channel not found: ${channelId}
• Cannot stream on orphan session ${session.id} — its agent wa
• Agent data file must be a real file: ${filePath}

AI-assisted analysis of CherryHQ/cherry-studio@726446b54c (2026-08-12). Data as JSON: /api/errors/3aa64dc40fc52fbc. Report an issue: GitHub.