Budibase/budibase · error · HTTPError

Agent not found

Error message

Agent not found

What it means

getOrThrow fetches the raw agent document from the workspace DB (db.tryGet) and throws a 404 HTTPError "Agent not found" if no document exists for the given agentId. It then applies defaults and resolves current query tool references before returning, guaranteeing callers a fully-hydrated Agent or an error.

Source

Thrown at packages/server/src/sdk/workspace/ai/agents/crud.ts:453

  }

  return resolved
}

export async function fetch(): Promise<Agent[]> {
  const agents = (await fetchRaw()).map(withAgentDefaults)
  return withCurrentQueryToolReferences(agents)
}

export async function getOrThrow(agentId: string | undefined): Promise<Agent> {
  if (!agentId) {
    throw new HTTPError("agentId is required", 400)
  }

  const db = context.getWorkspaceDB()
  const rawAgent = await db.tryGet<DeprecatedAgent>(agentId)
  if (!rawAgent) {
    throw new HTTPError("Agent not found", 404)
  }

  const agent = withAgentDefaults(rawAgent)
  const [resolvedAgent] = await withCurrentQueryToolReferences([agent])
  return resolvedAgent
}

export async function create(
  request: Optional<
    Omit<Agent, "_id" | "_rev" | "createdAt" | "updatedAt" | "publishedAt">,
    "aiconfig"
  >
): Promise<Agent> {
  const db = context.getWorkspaceDB()
  const now = new Date().toISOString()

  await guardName(request.name)

View on GitHub (pinned to a81a902e9a)

Solutions

  1. Verify the agentId exists in the current workspace DB (query the agents docs) — the id may be stale or from another workspace
  2. If the agent was deleted, clean up references (config, operations, tracking records) or recreate the agent with a new id
  3. Use sdk.ai.agents.fetch() to list valid ids and pick the correct one
  4. Catch the 404 HTTPError and handle gracefully (skip resolution, prompt re-selection of the agent)

Example fix

// before
const agent = await sdk.ai.agents.getOrThrow(session.agentId)
// after
let agent
try {
  agent = await sdk.ai.agents.getOrThrow(session.agentId)
} catch (err) {
  if (err instanceof HTTPError && err.status === 404) {
    // agent was deleted - rebind session to a valid agent
    agent = await sdk.ai.agents.getOrThrow(defaultAgentId)
  } else { throw err }
}
Defensive patterns

Strategy: try-catch

Validate before calling

const all = await sdk.ai.agents.fetch()
if (!all.some(a => a._id === agentId)) {
  // stale id - rebind to an existing agent before getOrThrow
}

Try / catch

try {
  agent = await sdk.ai.agents.getOrThrow(agentId)
} catch (err) {
  if (err instanceof HTTPError && err.status === 404) {
    // agent was deleted or id is from another workspace
    agent = await sdk.ai.agents.getOrThrow(fallbackAgentId)
  } else { throw err }
}

Prevention

When it happens

Trigger: Calling getOrThrow (or sdk.ai.agents.agent / getAgentId / sourceAgent / syncState paths) with a syntactically valid but non-existent agentId: agent deleted while a session/config still references it, wrong environment/workspace DB, typo in id, or a stale agentId persisted in another document (e.g. agentRequests, operations) after deletion.

Common situations: Agent deleted from the builder while automations or tracking records still hold its id; copy-pasting an agent id from another app/tenant; restoring a DB backup where agent docs were pruned; tests using hard-coded ids that don't exist in the test workspace.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/a765d720b1bd38b7. Report an issue: GitHub.