docusealco/docuseal · error · Error

Failed to start KBA

Error message

Failed to start KBA

What it means

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.

Source

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

        }

        if (payload.ssn) {
          payload.ssn = payload.ssn.replace(/\D/g, '')
        }

        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
          })

View on GitHub (pinned to 004a22c1c8)

Solutions

  1. Open the browser Network tab and inspect the POST /api/kba response: the status code plus the actual body fields reveal the real reason.
  2. Verify the credentials/entitlements of the KBA service behind baseUrl and that baseUrl matches the intended environment.
  3. Confirm the start payload (name, DOB/SSN, address, phone with leading +1 stripped) matches what the KBA API expects.
  4. Broaden the client fallback to surface alternate error fields and the HTTP status instead of a flat message.

Example fix

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

// after
if (!resp.ok) {
  throw new Error(data.error || data.message || data.detail || `Failed to start KBA (HTTP ${resp.status})`)
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (!payload.name || !payload.phone || !payload.ssn) {
  this.error = 'Please complete all personal details before starting verification.'
  return
}

Type guard

const extractApiError = (data, status) =>
  typeof data?.error === 'string' && data.error
    ? data.error
    : `Failed to start KBA (HTTP ${status})`

Try / catch

try {
  const resp = await fetch(this.baseUrl + '/api/kba', opts)
  const data = await resp.json()
  if (!resp.ok) throw new Error(extractApiError(data, resp.status))
  // ...
} catch (e) {
  this.error = e instanceof TypeError ? 'Network error, please try again.' : e.message
}

Prevention

When it happens

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

Common situations: 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.

Related errors

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