docusealco/docuseal · error · Error

Unfortunately, we were unable to start Knowledge Based Authe

Error message

Unfortunately, we were unable to start Knowledge Based Authentication with the details provided. Please review and confirm that all your personal details are correct.

What it means

The KBA service answered HTTP 200 with result.action === 'FAIL' and result.detail === 'NO MATCH': no identity record matched the personal details submitted, so no quiz could be generated. This is a business-level rejection from the identity bureau behind KBA, not a transport or code failure. The long friendly message exists because the fix is on the submitter's side: correct the personal data and try again.

Source

Thrown at app/javascript/submission_form/kba_step.vue:507

        }

        if (payload.phone) {
          payload.phone = payload.phone.replace(/^\+1/, '')
        }

        const resp = await fetch(this.baseUrl + '/api/kba', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(payload)
        })

        const data = await resp.json()

        if (!resp.ok) throw new Error(data.error || 'Failed to start KBA')

        if (data.result && data.result.action === 'FAIL') {
          if (data.result.detail === 'NO MATCH') {
            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.')
          }

          throw new Error(data.result.detail || 'KBA Start Failed')
        }

        if (data.output && data.output.questions && data.output.questions.questions) {
          this.questions = data.output.questions.questions
          this.token = data.continuations.questions.template.token
          this.reference = data.meta.reference

          this.questions.forEach(q => {
            this.answers[q.id] = null
          })

          this.startCountdown()
        } else {
          throw new Error('Invalid KBA response')
        }

View on GitHub (pinned to 004a22c1c8)

Solutions

Have the submitter re-enter every personal detail exactly as it appears on official records (SSN card, license, credit-report address) and retry.
Verify that the earlier form steps actually mapped the right values into the KBA start payload.
Confirm you are not sending test data to a production KBA provider or production data to a sandbox.
If the identity is real but still unmatched, switch the field to a different verification method or route to manual review.

Defensive patterns

Strategy: validation

Validate before calling

const ssnRe = /^(?!000|666|9\d\d)\d{3}-?\d{2}-?\d{4}$/
if (!ssnRe.test(payload.ssn || '') || !/^\d{4}-\d{2}-\d{2}$/.test(payload.dob || '')) {
  this.error = 'Please check your SSN and date of birth formats before starting.'
  return
}

Prevention

Validate identity field formats client-side before starting KBA
Tell submitters that details must match official and bureau records
Normalize names and strip non-digits from SSN and phone before sending

When it happens

Trigger: Starting KBA with a name/DOB/SSN/address combination that matches no bureau record: typos, transposed SSN digits, a former home address, or genuinely thin-file consumers with no credit history. Also fabricated test personas (fake name + fake SSN) sent to the real provider.

Common situations: QA testing with made-up identities; submitters with credit freezes; users entering a work address instead of the residential address on file; picking the wrong party on multi-submitter forms.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of docusealco/docuseal@004a22c1c8 (2026-08-21). Data as JSON: /api/errors/47832a775766b0d0. Report an issue: GitHub.