{"record":{"id":"2ea4aef93e87e408","repo":"passbolt/passbolt_api","slug":"something-went-wrong-when-validating-the-one-time-password","errorCode":null,"errorMessage":"Something went wrong when validating the one-time password.","messagePattern":"Something went wrong when validating the one-time password\\.","errorType":"validation","errorClass":"CustomValidationException","httpStatus":null,"severity":"error","filePath":"plugins/PassboltCe/MultiFactorAuthentication/src/Form/MfaForm.php","lineNumber":57,"sourceCode":"    }\n\n    /**\n     * Execute the form if it is valid.\n     *\n     * First validates the form, then calls the `process()` hook method.\n     * This hook method can be implemented in subclasses to perform\n     * the action of the form. This may be sending email, interacting\n     * with a remote API, or anything else you may need.\n     *\n     * @param array $data Form data.\n     * @param array<string, mixed> $options List of options.\n     * @return bool False on validation failure, otherwise returns the\n     *   result of the `process()` method.\n     */\n    public function execute(array $data, array $options = []): bool\n    {\n        if (!$this->validate($data)) {\n            throw new CustomValidationException(\n                __('Something went wrong when validating the one-time password.'),\n                $this->getErrors()\n            );\n        }\n\n        return $this->process($data);\n    }\n}\n","sourceCodeStart":39,"sourceCodeEnd":66,"githubUrl":"https://github.com/passbolt/passbolt_api/blob/31c1bbc10f32808a607fa9bd81891e898779c0bc/plugins/PassboltCe/MultiFactorAuthentication/src/Form/MfaForm.php#L39-L66","documentation":"The base MFA form's `execute()` throws a CustomValidationException when the submitted data fails the form's validation rules (e.g. a bad TOTP code or missing field). The message is generic on purpose; the precise per-field reasons are returned in the attached `getErrors()` array.","triggerScenarios":"POSTing MFA verify/setup data that fails the form's rules: empty or non-6-digit OTP, wrong TOTP code, missing `otp` field, invalid Yubikey HOTP format, or data not matching the declared validation schema.","commonSituations":"Authenticator app out of sync (TOTP window passed); users submitting the recovery code into the OTP field; frontend sending form data as multipart instead of JSON so fields are missing; expired provisioning URI.","solutions":["Read the `body.errors` object in the API response for the exact failing field(s)","Regenerate/resynchronize the authenticator app time and retry with a fresh code","Ensure all required fields (e.g. `totp`) are present in the JSON payload","If verifying Yubikey, confirm the org Yubikey client-id/secret-key settings exist"],"exampleFix":"// before\nconst res = await post('/mfa/verify/totp.json', {totp: code});\nif (!res.ok) alert('invalid code');\n// after\nconst res = await post('/mfa/verify/totp.json', {totp: code});\nif (!res.ok) {\n  const errs = (await res.json()).errors; // per-field details\n  showFieldErrors(errs);\n}","handlingStrategy":"try-catch","validationCode":"const TOTP_RE = /^\\d{6}$/;\nif (!TOTP_RE.test(otp)) throw new Error('OTP must be exactly 6 digits');","typeGuard":"function isValidTotp(v) { return typeof v === 'string' && /^\\d{6}$/.test(v); }","tryCatchPattern":"try { await verifyMfa(data); } catch (e) {\n  if (e.response?.data?.errors) showFieldErrors(e.response.data.errors);\n}","preventionTips":["Always inspect the errors object in the response for per-field reasons","Validate OTP format client-side before submitting","Keep authenticator clocks synchronized","Send the payload as JSON with all required fields"],"tags":["mfa","validation","totp","bad-request"],"backgroundTag":"schema-validation-failed","analyzedSha":"31c1bbc10f32808a607fa9bd81891e898779c0bc","analyzedAt":"2026-09-17T00:04:38.960Z","contentChangedAt":"2026-09-17T00:04:38.960Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}