Budibase/budibase · warning · HTTPError

Knowledge source downloads are disabled for this operation

Error message

Knowledge source downloads are disabled for this operation

What it means

Thrown by fetchAgentFileUrl with HTTP 403 when allowsKnowledgeSourceDownload indicates the agent's operation is not permitted to download knowledge source files. This is a policy check on the agent config, not an authentication failure.

Source

Thrown at packages/server/src/api/controllers/ai/files.ts:275

  >
) {
  const { agentId, operationId, fileId } = ctx.params
  await sdk.ai.rag.deleteFileForOperation(agentId, operationId, fileId)
  ctx.body = { deleted: true }
  ctx.status = 200
}

export async function fetchAgentFileUrl(
  ctx: UserCtx<
    void,
    FetchAgentFileUrlResponse,
    { agentId: string; operationId: string; fileId: string }
  >
) {
  const { agentId, operationId, fileId } = ctx.params
  const agent = await sdk.ai.agents.getOrThrow(agentId)
  if (!allowsKnowledgeSourceDownload(agent, operationId)) {
    throw new HTTPError(
      "Knowledge source downloads are disabled for this operation",
      403
    )
  }
  const url = await sdk.ai.rag.getFileUrlForOperation(
    agentId,
    operationId,
    fileId
  )
  ctx.body = { url }
  ctx.status = 200
}

export async function fetchAgentKnowledgeSourceOptions(
  ctx: UserCtx<
    void,
    FetchAgentKnowledgeSourceOptionsResponse,
    { datasourceId: string; authConfigId: string }

View on GitHub (pinned to a81a902e9a)

Solutions

Enable knowledge source downloads for the operation in the agent configuration.
Check the agent's operation config (via sdk.ai.agents.getOrThrow or the API) before exposing download actions.
Re-fetch the agent to ensure the operationId is current.
Handle 403 distinctly from 404 in client error handling (policy vs not-found).

Example fix

// before
const { url } = await api.getAgentFileUrl(agentId, operationId, fileId)
// after
const agent = await api.getAgent(agentId)
if (!agent.operations.find(op => op.id === operationId)?.knowledgeSourceDownloadEnabled) return null
const { url } = await api.getAgentFileUrl(agentId, operationId, fileId)

Defensive patterns

Strategy: validation

Validate before calling

const agent = await api.getAgent(agentId)
const op = agent.operations?.find(op => op.id === operationId)
if (!op?.knowledgeSourceDownloadEnabled) throw new Error("downloads disabled for this operation")

Type guard

function canDownload(agent, operationId) {
  return Boolean(agent?.operations?.some(op => op.id === operationId && op.knowledgeSourceDownloadEnabled))
}

Try / catch

try {
  const { url } = await api.getAgentFileUrl(agentId, operationId, fileId)
} catch (err) {
  if (err.status === 403) {
    // enable knowledge source download for the operation or hide the UI action
  } else throw err
}

Prevention

Enable knowledge-source download in the operation's configuration before exposing download links.
Check the agent's operation config before rendering download buttons.
Distinguish 403 (policy) from 404 (wrong fileId) in client error handling.
Keep operation IDs current; stale IDs after agent edits can fail the policy check.

When it happens

Trigger: Requesting a download URL for an operation whose configuration has knowledge source downloads disabled; using a stale operationId after the agent's operations were edited; calling the endpoint for an operation type that never allows downloads.

Common situations: UI exposing download buttons without checking the operation's download capability; clients caching agent config and hitting the endpoint after an admin disabled downloads; automation scripts assuming downloads are always allowed.

Related errors

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