{"record":{"id":"2232408e68db99db","repo":"QuantumNous/new-api","slug":"failed-to-start-telegram-binding","errorCode":null,"errorMessage":"Failed to start Telegram binding","messagePattern":"Failed to start Telegram binding","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"web/src/features/profile/components/dialogs/telegram-bind-dialog.tsx","lineNumber":63,"sourceCode":"  open,\n  onOpenChange,\n  botName,\n  onSuccess,\n}: TelegramBindDialogProps) {\n  const { t } = useTranslation()\n  const widgetRef = useRef<HTMLDivElement>(null)\n  const [callbackUrl, setCallbackUrl] = useState<string | null>(null)\n  const [flowToken, setFlowToken] = useState<string | null>(null)\n  const [loading, setLoading] = useState(false)\n  const [error, setError] = useState<string | null>(null)\n\n  const createBindFlow = useCallback(async () => {\n    setLoading(true)\n    setError(null)\n    try {\n      const response = await startTelegramBind()\n      if (!response.success || !response.data?.callback_url) {\n        throw new Error(\n          response.message || t('Failed to start Telegram binding')\n        )\n      }\n      setFlowToken(response.data.flow_token)\n      setCallbackUrl(\n        new URL(response.data.callback_url, window.location.origin).toString()\n      )\n    } catch (bindError: unknown) {\n      setError(\n        bindError instanceof Error\n          ? bindError.message\n          : t('Failed to start Telegram binding')\n      )\n    } finally {\n      setLoading(false)\n    }\n  }, [t])\n","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/QuantumNous/new-api/blob/e2c7aa7b102c2075eae2377df3508658d45e88dc/web/src/features/profile/components/dialogs/telegram-bind-dialog.tsx#L45-L81","documentation":"Thrown by createBindFlow in the Telegram bind dialog when startTelegramBind() returns success=false or the payload lacks data.callback_url. The flow needs a backend-issued callback_url (plus flow_token) to render the Telegram widget; on failure the message is stored in the dialog's error state.","triggerScenarios":"Clicking start binding when the backend cannot initiate the flow: Telegram bot/OAuth settings missing server-side, the provider not configured, flow creation rejected, or response missing callback_url (contract violation).","commonSituations":"Admin enabled Telegram login in UI but did not set bot token/secret in system settings; backend env for the OAuth provider absent; session expired mid-dialog; backend version returns a different payload shape.","solutions":["Verify Telegram OAuth settings (bot token, callback secret) are fully configured in admin system settings","Read the dialog's error text — response.message identifies 'not configured' vs other causes","Re-login and reopen the dialog to refresh the session-bound flow token","Confirm the backend version returns { flow_token, callback_url } for the bind-start endpoint"],"exampleFix":"// before\nif (!response.success || !response.data?.callback_url) {\n  throw new Error(response.message || t('Failed to start Telegram binding'))\n}\n// after - distinguish 'not configured' with an actionable hint\nif (!response.success || !response.data?.callback_url) {\n  const msg = response.message || t('Failed to start Telegram binding')\n  throw new Error(\n    /config|provider/i.test(msg)\n      ? `${msg} — ${t('Ask the admin to configure Telegram login')}`\n      : msg\n  )\n}","handlingStrategy":"try-catch","validationCode":"if (loading) return // prevent duplicate flow creation\n// verify backend telegram OAuth is configured before showing the bind button","typeGuard":"const isBindFlowPayload = (d: unknown): d is { flow_token: string; callback_url: string } =>\n  !!d && typeof (d as any).flow_token === 'string' && typeof (d as any).callback_url === 'string'","tryCatchPattern":"setLoading(true)\nsetError(null)\ntry {\n  const response = await startTelegramBind()\n  if (!response.success || !isBindFlowPayload(response.data)) {\n    throw new Error(response.message || t('Failed to start Telegram binding'))\n  }\n  setFlowToken(response.data.flow_token)\n  setCallbackUrl(new URL(response.data.callback_url, window.location.origin).toString())\n} catch (bindError: unknown) {\n  setError(bindError instanceof Error ? bindError.message : t('Failed to start Telegram binding'))\n} finally {\n  setLoading(false)\n}","preventionTips":["Check the server's Telegram provider status endpoint before rendering the bind entry point","Guard on both success and the payload shape (callback_url present)","Keep flow_token single-use: restart the flow on error instead of reusing it"],"tags":["api-error","telegram","oauth-binding","profile","dialog"],"backgroundTag":null,"analyzedSha":"e2c7aa7b102c2075eae2377df3508658d45e88dc","analyzedAt":"2026-08-15T10:35:18.111Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}