What causes "Knowledge Based Authentication Failed" in docusealco/docuseal?

Have the submitter start a fresh KBA session and answer carefully - note that providers cap retry attempts.

docusealco/docuseal · error · Error

Knowledge Based Authentication Failed

Error message

Knowledge Based Authentication Failed

What it means

After answers are POSTed to /api/kba/{field.uuid}, the response's result.action is not 'PASS': the quiz answers did not meet the provider's pass threshold. When result.issues is a non-empty array its entries are appended to the visible error text. The thrown 'Knowledge Based Authentication Failed' is the signal that this verification attempt failed at the business level.

Source

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

          body: JSON.stringify({
            token: this.token,
            answers: formattedAnswers,
            reference: this.reference,
            submitter_slug: this.submitterSlug
          }),
          headers: { 'Content-Type': 'application/json' }
        })

        const data = await resp.json()

        if (data.result?.action !== 'PASS') {
          if (data.result?.issues?.length) {
            this.error = `Knowledge Based Authentication Failed - make sure you provide correct details for the Knowledge Based authentication: ${data.result.issues.join(', ')}`
          } else {
            this.error = 'Knowledge Based Authentication Failed - make sure you provide correct answers for the Knowledge Based authentication.'
          }

          throw new Error('Knowledge Based Authentication Failed')
        }

        if (!resp.ok) {
          this.error = 'Failed to submit answers'

          throw new Error('Failed to submit answers')
        }

        return resp
      } finally {
        this.isSubmitting = false
      }
    }
  }
}
</script>

View on GitHub (pinned to 004a22c1c8)

Solutions

Have the submitter start a fresh KBA session and answer carefully - note that providers cap retry attempts.
Enforce the countdown client-side so users cannot submit expired sessions.
Surface data.result.issues to the signer or support for the exact failure criteria.
If retries are exhausted, fall back to an alternate verification method or manual review.

Defensive patterns

Strategy: retry

Validate before calling

if (this.questions.some((q) => this.answers[q.id] == null)) {
  this.error = 'Please answer all questions before submitting.'
  return
}
if (this.timeLeft <= 0) {
  this.error = 'Time has expired, please restart verification.'
  return
}

Try / catch

try {
  await this.submit()
} catch (e) {
  this.error = e.message // already includes issues detail; let the user restart the flow
}

Prevention

Require all answers before enabling submit
Disable submit when the countdown reaches zero
Track attempt counts against provider retry limits

When it happens

Trigger: Too many incorrect answers; submitting after the countdown expired so the session auto-failed; reusing a token from a previous session; provider returns result.issues listing the failed criteria.

Common situations: Legitimate signers misremembering historical details (old addresses, loans); deliberate impostor attempts; slow users hitting the time limit and submitting a dead session.

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/9f848c9ddb8b48f7. Report an issue: GitHub.