{"record":{"id":"07450703aedfc24d","repo":"paperclipai/paperclip","slug":"agent-not-found-074507","errorCode":"agent_not_found","errorMessage":"agent_not_found: Agent not found.","messagePattern":"agent_not_found: Agent not found\\.","errorType":"error_code","errorClass":"RunnerGoalActionError","httpStatus":null,"severity":"error","filePath":"server/src/services/runner-goals.ts","lineNumber":358,"sourceCode":"      sessionId: session?.id ?? null,\n      capability: storedCapability(session, capabilityForAgent(binding.agent)),\n      goal,\n      workingNow: goal?.workingNow ?? false,\n      activeRunId: activeRun?.id ?? null,\n      pendingAction: projectedPendingAction,\n      revision: session?.goalRevision ?? 0,\n      observedAt: session?.goalObservedAt?.toISOString() ?? null,\n    };\n  }\n\n  async function act(\n    companyId: string,\n    issueId: string,\n    request: RunnerGoalActionRequest,\n  ): Promise<RunnerGoalActionAccepted> {\n    const binding = await readBinding(companyId, issueId, request.agentId);\n    if (!binding) throw new RunnerGoalActionError(\"issue_not_found\", \"Issue not found.\");\n    if (!binding.agent) throw new RunnerGoalActionError(\"agent_not_found\", \"Agent not found.\");\n    if (binding.issue.assigneeAgentId !== request.agentId) {\n      throw new RunnerGoalActionError(\"agent_not_assigned\", \"The selected agent is not assigned to this issue.\");\n    }\n    const fallbackCapability = capabilityForAgent(binding.agent);\n    const initialProjection = await projection(companyId, issueId, request.agentId);\n    if (!initialProjection) throw new RunnerGoalActionError(\"issue_not_found\", \"Issue not found.\");\n    if (initialProjection.capability.availability !== \"available\") {\n      throw new RunnerGoalActionError(\n        initialProjection.capability.reasonCode ?? \"session_goals_unsupported\",\n        initialProjection.capability.reason ?? \"Session goals are unsupported.\",\n      );\n    }\n\n    const accepted = await db.transaction(async (tx) => {\n      await tx.insert(agentTaskSessions).values({\n        companyId,\n        agentId: request.agentId,\n        adapterType: binding.agent!.adapterType,","sourceCodeStart":340,"sourceCodeEnd":376,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/server/src/services/runner-goals.ts#L340-L376","documentation":"`act` also validates the agent. If the issue exists but the requested agentId does not resolve to an agent on the binding (readBinding returned a binding whose agent is undefined), it throws RunnerGoalActionError with code 'agent_not_found'. Note this is distinct from agent_not_assigned, which fires when the agent exists but is not the issue's assignee.","triggerScenarios":"Calling the runner-goal action with an agentId that does not exist within the company — deleted agent, id from another company, wrong id field passed (e.g. adapter id instead of agent id), or the agent record was removed after the binding snapshot.","commonSituations":"Agent was deleted/rotated while a client still held its id; mixing up agent vs assignment vs user ids; cross-company ids due to shared tooling; stale configuration referencing a removed agent.","solutions":["List agents for the companyId and confirm the agentId exists before acting","Use the issue's current assigneeAgentId when the intent is to act as the assignee","Update stale configs/clients that reference deleted agent ids","Distinguish the failure: agent_not_found means bad id, agent_not_assigned means wrong-but-existing agent — fix the request accordingly"],"exampleFix":"// before: acting with a hardcoded agent id\nconst request = { agentId: 'agent_legacy_1', ... };\nawait act(companyId, issueId, request);\n// after: resolve a live agent id\nconst agent = await getAgent(companyId, issue.assigneeAgentId);\nconst request = { agentId: agent.id, ... };\nawait act(companyId, issueId, request);","handlingStrategy":"try-catch","validationCode":"const agents = await listAgents(companyId);\nif (!agents.some(a => a.id === request.agentId)) {\n  throw new Error(`Agent ${request.agentId} not found in company ${companyId}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await act(companyId, issueId, request);\n} catch (e) {\n  if (e instanceof RunnerGoalActionError && e.code === 'agent_not_found') {\n    // resolve a live agentId (e.g. issue.assigneeAgentId) and retry\n  } else if (e instanceof RunnerGoalActionError && e.code === 'agent_not_assigned') {\n    // agent exists but is not the assignee; fix the request\n  } else throw e;\n}","preventionTips":["Validate the agentId against the company's agent list before calling act","Prefer deriving agentId from the issue's current assignee","Clean up stale references when agents are deleted or rotated","Distinguish agent_not_found (bad id) from agent_not_assigned (wrong agent) in client handling"],"tags":["runner-goals","agent","not-found"],"backgroundTag":"resource-not-found","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}