docusealco/docuseal · error · Error

KBA Start Failed

Error message

KBA Start Failed

What it means

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.

Source

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

          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')
        }
      } catch (e) {
        this.error = e.message
      } finally {

View on GitHub (pinned to 004a22c1c8)

Solutions

  1. Capture and surface data.result.detail (in logs or the thrown message) - it is the provider's stated reason.
  2. Check the KBA account status and entitlements for the environment behind baseUrl.
  3. Retry once for transient provider degradation; persistent FAIL indicates configuration.
  4. Compare the start payload against the provider's current API schema for newly required fields.

Example fix

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

// after
throw new Error(data.result.detail ? `KBA Start Failed: ${data.result.detail}` : 'KBA Start Failed')
Defensive patterns

Strategy: try-catch

Type guard

const kbaStartFailed = (data) =>
  data?.result?.action === 'FAIL' && data?.result?.detail !== 'NO MATCH'

Try / catch

try {
  await this.startKba()
} catch (e) {
  this.error = e.message
  // capture the provider detail for diagnostics
  telemetry.captureMessage(`KBA start failed for field ${this.field.uuid}`)
}

Prevention

When it happens

Trigger: 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.

Common situations: Newly provisioned KBA account without production entitlements; provider maintenance windows; bureau does not cover the subject's region or profile.

Related errors

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