{"record":{"id":"42f319f9d92675ff","repo":"toeverything/AFFiNE","slug":"copilot-selected-sources-unavailable","errorCode":"copilot_selected_sources_unavailable","errorMessage":"Selected sources are not available for AI retrieval.","messagePattern":"Selected sources are not available for AI retrieval\\.","errorType":"exception","errorClass":"CopilotSelectedSourcesUnavailable","httpStatus":403,"severity":"error","filePath":"packages/backend/server/src/core/backend-runtime/job.ts","lineNumber":72,"sourceCode":"      return new CopilotSelectedSourcesProcessing();\n    }\n    if (message.includes('embedding_selected_sources_failed')) {\n      return new CopilotSelectedSourcesFailed();\n    }\n    if (message.includes('embedding_selected_sources_unavailable')) {\n      return new CopilotSelectedSourcesUnavailable();\n    }\n    return error;\n  }\n\n  private async syncDocuments(\n    workspaceId: string,\n    docIds: string[],\n    reconcileDocuments: boolean,\n    scheduling?: { priority: number; waitForReadyMs: number }\n  ) {\n    if (!(await this.rt.embeddingHealth()).enabled) {\n      if (scheduling) throw new CopilotSelectedSourcesUnavailable();\n      return;\n    }\n    const enabled = await this.models.workspace.allowEmbedding(workspaceId);\n    if (!enabled) {\n      if (scheduling) throw new CopilotSelectedSourcesUnavailable();\n      return;\n    }\n    const documents = [];\n    let unitCount = 0;\n    let textBytes = 0;\n    for (const docId of docIds) {\n      const snapshot = await this.models.doc.getSnapshot(workspaceId, docId);\n      if (!snapshot) {\n        if (scheduling) throw new CopilotSelectedSourcesUnavailable();\n        continue;\n      }\n      const revision = snapshot.updatedAt.getTime().toString();\n      const projection = projectDocSearch(snapshot.blob, docId, revision);","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/toeverything/AFFiNE/blob/2af30773aecd567f09b346e7b72fc69143144057/packages/backend/server/src/core/backend-runtime/job.ts#L54-L90","documentation":"Thrown from syncDocuments (job.ts:123-125) when preparing user-selected sources: this.rt.embeddingHealth() reports the embedding backend as not enabled, so selected-source retrieval cannot be served. It is an 'action_forbidden' error: background embedding sync silently skips (scheduling unset), but an explicit user selection fails loudly.","triggerScenarios":"prepareSelectedDocuments -> syncDocuments with scheduling set, while the backend runtime's embedding health endpoint returns enabled=false (embedding runtime not deployed, not configured, or unhealthy).","commonSituations":"Self-hosted deployment without the embedding runtime configured; embedding capability disabled at the instance level; missing credentials/endpoint for the backend runtime so the health check reports disabled.","solutions":["Enable and configure the embedding backend runtime for the deployment and verify embeddingHealth().enabled becomes true.","Check the backend-runtime provider configuration (endpoint/credentials/feature flags) in the server environment.","If embeddings are intentionally off, stop sending retrieval scope mode 'required' and chat without selected sources."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const health = await backendRuntime.embeddingHealth();\nif (!health.enabled) {\n  // hide 'required' retrieval option; chat without selected sources\n}","typeGuard":null,"tryCatchPattern":"try {\n  await prepareSelectedDocuments(workspaceId, requiredDocIds);\n} catch (e) {\n  if (getErrorCode(e) === 'copilot_selected_sources_unavailable') {\n    // surface 'AI retrieval unavailable' and fall back to plain chat without retrieval scope\n  } else throw e;\n}","preventionTips":["Gate the selected-sources UI on the deployment's embedding health check.","On self-hosted, verify embedding runtime configuration before enabling AI retrieval features.","Never retry the same request - unavailability is a config state, not a transient fault."],"tags":["copilot","embedding","feature-unavailable","runtime-config","ai-retrieval"],"backgroundTag":"feature-not-enabled","analyzedSha":"2af30773aecd567f09b346e7b72fc69143144057","analyzedAt":"2026-08-18T21:16:52.546Z","contentChangedAt":"2026-08-18T21:16:52.546Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}