{"record":{"id":"334bc67a03ddc1b1","repo":"docusealco/docuseal","slug":"failed-to-start-kba","errorCode":null,"errorMessage":"Failed to start KBA","messagePattern":"Failed to start KBA","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"app/javascript/submission_form/kba_step.vue","lineNumber":503,"sourceCode":"        }\n\n        if (payload.ssn) {\n          payload.ssn = payload.ssn.replace(/\\D/g, '')\n        }\n\n        if (payload.phone) {\n          payload.phone = payload.phone.replace(/^\\+1/, '')\n        }\n\n        const resp = await fetch(this.baseUrl + '/api/kba', {\n          method: 'POST',\n          headers: { 'Content-Type': 'application/json' },\n          body: JSON.stringify(payload)\n        })\n\n        const data = await resp.json()\n\n        if (!resp.ok) throw new Error(data.error || 'Failed to start KBA')\n\n        if (data.result && data.result.action === 'FAIL') {\n          if (data.result.detail === 'NO MATCH') {\n            throw new Error('Unfortunately, we were unable to start Knowledge Based Authentication with the details provided. Please review and confirm that all your personal details are correct.')\n          }\n\n          throw new Error(data.result.detail || 'KBA Start Failed')\n        }\n\n        if (data.output && data.output.questions && data.output.questions.questions) {\n          this.questions = data.output.questions.questions\n          this.token = data.continuations.questions.template.token\n          this.reference = data.meta.reference\n\n          this.questions.forEach(q => {\n            this.answers[q.id] = null\n          })\n","sourceCodeStart":485,"sourceCodeEnd":521,"githubUrl":"https://github.com/docusealco/docuseal/blob/004a22c1c88109c7ba0b567df011a8cb13894001/app/javascript/submission_form/kba_step.vue#L485-L521","documentation":"Thrown by the KBA (Knowledge Based Authentication) step of the submission form when POST {baseUrl}/api/kba returns a non-2xx status whose JSON body has no 'error' field, making it the generic client-side fallback. baseUrl is injected from the host page and points at the form/KBA backend service, so the real cause lives in that backend response (auth failure, misconfiguration, rejected identity payload). The component catches it and only displays the message string, so the HTTP status is lost unless you capture it.","triggerScenarios":"POST to {baseUrl}/api/kba answers 4xx/5xx with a JSON body not shaped as { error: '...' } - e.g. { message: ... } from an API gateway or {} from a 500. Typical concrete cases: missing/expired KBA credentials on the service, wrong baseUrl environment, or a provider outage answered by a proxy with a JSON status body.","commonSituations":"Enabling KBA fields without valid KBA entitlements on the backend; staging frontend pointing at production baseUrl or vice versa; API gateways that rewrite error bodies into a different shape; provider 502/503 during incidents.","solutions":["Open the browser Network tab and inspect the POST /api/kba response: the status code plus the actual body fields reveal the real reason.","Verify the credentials/entitlements of the KBA service behind baseUrl and that baseUrl matches the intended environment.","Confirm the start payload (name, DOB/SSN, address, phone with leading +1 stripped) matches what the KBA API expects.","Broaden the client fallback to surface alternate error fields and the HTTP status instead of a flat message."],"exampleFix":"// before\nif (!resp.ok) throw new Error(data.error || 'Failed to start KBA')\n\n// after\nif (!resp.ok) {\n  throw new Error(data.error || data.message || data.detail || `Failed to start KBA (HTTP ${resp.status})`)\n}","handlingStrategy":"try-catch","validationCode":"if (!payload.name || !payload.phone || !payload.ssn) {\n  this.error = 'Please complete all personal details before starting verification.'\n  return\n}","typeGuard":"const extractApiError = (data, status) =>\n  typeof data?.error === 'string' && data.error\n    ? data.error\n    : `Failed to start KBA (HTTP ${status})`","tryCatchPattern":"try {\n  const resp = await fetch(this.baseUrl + '/api/kba', opts)\n  const data = await resp.json()\n  if (!resp.ok) throw new Error(extractApiError(data, resp.status))\n  // ...\n} catch (e) {\n  this.error = e instanceof TypeError ? 'Network error, please try again.' : e.message\n}","preventionTips":["Check resp.ok before reading business fields from data","Always embed the HTTP status in fallback error messages","Log the raw response body when the shape is unexpected"],"tags":["kba","identity-verification","fetch","frontend","http-error"],"backgroundTag":"http-error-response","analyzedSha":"004a22c1c88109c7ba0b567df011a8cb13894001","analyzedAt":"2026-08-21T13:38:23.343Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}