CherryHQ/cherry-studio · error · Error

Agent not found: ${agentId}

Error message

Agent not found: ${agentId}

What it means

Thrown by AgentJobsService.assertAgentExists when agentService.getAgent(agentId) returns a falsy value — i.e. no agent with the given id exists. The guard runs before binding a task schedule or trigger to an agent. The code deliberately throws a plain Error (not an IpcError with a domain code) because no renderer branch needs to branch on a not-found code; the message surfaces via the generic INTERNAL path to a toast.

Source

Thrown at src/main/ai/agents/AgentJobsService.ts:269

        return false
      }
      return agentSessionService.bindTaskScheduleTx(tx, {
        sessionId: params.sessionId,
        taskScheduleId: params.scheduleId,
        expectedAgentId: params.agentId
      })
    })
    if (bound) agentTaskService.notifyReadModelChange([params.scheduleId])
    return bound
  }

  // Plain Errors on purpose: no renderer branch consumes an agent/channel
  // not-found code (the message reaches the toast through INTERNAL either
  // way), so no AI-domain IpcError code is minted for them — unlike trigger
  // validation, where the form must branch on the code.
  private assertAgentExists(agentId: string): void {
    if (!agentService.getAgent(agentId)) {
      throw new Error(`Agent not found: ${agentId}`)
    }
  }

  private assertChannelsBelongToAgent(agentId: string, channelIds: readonly string[]): void {
    for (const channelId of channelIds) {
      const channel = agentChannelService.getChannel(channelId)
      if (!channel || channel.agentId !== agentId) {
        throw new Error(`Channel not found: ${channelId}`)
      }
    }
  }
}

View on GitHub (pinned to 726446b54c)

Solutions

1. Verify the agent exists before submitting the schedule/trigger: ensure the agentId is present in the current agents list and refresh if stale.
2. If the agent was deleted intentionally, remove or rebind the dependent schedules/triggers to a valid agent.
3. On the UI side, invalidate cached agent references when an agent is deleted so the user cannot submit a stale id.
4. If importing data, map or create the referenced agents before binding schedules.

// Before binding a schedule/trigger, confirm the agent exists
if (!agentService.getAgent(agentId)) {
  throw new Error(`Cannot bind: agent '${agentId}' does not exist`)
}

const agentExists = (id: string): boolean => agentService.getAgent(id) != null

When it happens

Trigger: Creating or binding a task schedule/trigger for an agentId that was deleted, never existed, or whose id is stale (e.g. from an imported/duplicated config). Also when an agent is deleted while a pending schedule/trigger operation references it.

Common situations: User deletes an agent that still has scheduled tasks or triggers; importing a workspace/config that references agents not present in the target; race between agent deletion and a concurrent schedule operation; stale agentId cached in the UI after the agent was removed.

Related errors

• Channel not found: ${channelId}
• Unsupported agent runtime type: ${entry.agentType}
• Agent storage path escapes its root: ${target}
• Agent storage root must be a real directory: ${root}
• Agent storage path parent is not a directory: ${current}

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