{"record":{"id":"7737551c25130c29","repo":"docusealco/docuseal","slug":"kba-start-failed","errorCode":null,"errorMessage":"KBA Start Failed","messagePattern":"KBA Start Failed","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"app/javascript/submission_form/kba_step.vue","lineNumber":510,"sourceCode":"          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\n          this.startCountdown()\n        } else {\n          throw new Error('Invalid KBA response')\n        }\n      } catch (e) {\n        this.error = e.message\n      } finally {","sourceCodeStart":492,"sourceCodeEnd":528,"githubUrl":"https://github.com/docusealco/docuseal/blob/004a22c1c88109c7ba0b567df011a8cb13894001/app/javascript/submission_form/kba_step.vue#L492-L528","documentation":"Catch-all for a KBA start that failed at the provider level: result.action === 'FAIL' with detail missing or anything other than 'NO MATCH'. The provider returned a structured failure (for example questions unavailable, account misprovisioned, policy refusal) and detail, when present, carries the provider's reason string. The generic 'KBA Start Failed' message means detail was empty.","triggerScenarios":"Provider returns FAIL with a detail like 'QUESTIONS UNAVAILABLE' or an empty detail; the KBA account is not entitled in this environment; provider-side degradation during incidents; requests that pass HTTP validation but fail the provider's business rules.","commonSituations":"Newly provisioned KBA account without production entitlements; provider maintenance windows; bureau does not cover the subject's region or profile.","solutions":["Capture and surface data.result.detail (in logs or the thrown message) - it is the provider's stated reason.","Check the KBA account status and entitlements for the environment behind baseUrl.","Retry once for transient provider degradation; persistent FAIL indicates configuration.","Compare the start payload against the provider's current API schema for newly required fields."],"exampleFix":"// before\nthrow new Error(data.result.detail || 'KBA Start Failed')\n\n// after\nthrow new Error(data.result.detail ? `KBA Start Failed: ${data.result.detail}` : 'KBA Start Failed')","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"const kbaStartFailed = (data) =>\n  data?.result?.action === 'FAIL' && data?.result?.detail !== 'NO MATCH'","tryCatchPattern":"try {\n  await this.startKba()\n} catch (e) {\n  this.error = e.message\n  // capture the provider detail for diagnostics\n  telemetry.captureMessage(`KBA start failed for field ${this.field.uuid}`)\n}","preventionTips":["Handle every documented FAIL detail code explicitly","Log provider detail strings for trend analysis","Keep provider credentials and entitlements current"],"tags":["kba","identity-verification","provider-error"],"backgroundTag":"identity-verification-failed","analyzedSha":"004a22c1c88109c7ba0b567df011a8cb13894001","analyzedAt":"2026-08-21T13:38:23.343Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}