unexpected two-factor requirement during registration

Error message

unexpected two-factor requirement during registration

What it means

This error is thrown by `atuin register` when the registration API call to the sync server unexpectedly responds with a two-factor-authentication requirement. Registration of a brand-new account should never require 2FA (no 2FA has been configured yet), so the CLI treats this response as unexpected and aborts instead of continuing the key-generation/linking flow.

Solutions

Check `sync_address` in your config; make sure you are registering against the server you intend (standard atuin servers do not require 2FA on register).
If you already have an account, use `atuin login` instead of `atuin register`.
If the target server enforces 2FA at registration, complete registration/2FA through the server's web UI, then link with `atuin account link` / `atuin login`.
Inspect the server deployment for an unexpected 2FA-on-register policy if this is your own instance.

Example fix

// before
atuin register -u me -e me@example.com
// (fails: unexpected two-factor requirement)
// after
# register on the correct server / use the web UI for 2FA servers
atuin register -u me -e me@example.com  # with sync_address unset or pointing at a non-2FA server

Defensive patterns

Strategy: try-catch

Validate before calling

# verify sync_address before registering
grep -E 'sync_address|two_factor' ~/.config/atuin/config.toml; echo "registering against: ${ATUIN_SYNC_ADDRESS:-default}"

Try / catch

match atuin::register(&username, &email, &password) {
    Err(e) if e.to_string().contains("two-factor requirement") => {
        eprintln!("This server requires 2FA at registration; use the web UI or `atuin login`.");
    }
    Err(e) => return Err(e),
    Ok(session) => { /* proceed */ }
}

Prevention

Confirm sync_address points at the intended server before registering.
Use `atuin login` for accounts that already exist or have 2FA.
Complete 2FA enrollment via the server's web UI, then link the CLI.
Document non-standard sync_address values in team setup guides.

When it happens

Trigger: Running `atuin register` against a server whose `register` endpoint returns `AuthResponse::TwoFactorRequired` — e.g. registering on a hub/server that enforces 2FA at account-creation time, or hitting a different (2FA-enabled) endpoint than intended via a custom `sync_address`.

Common situations: Pointing `sync_address` at a non-standard server (e.g. an Atuin Hub instance with mandatory 2FA) while trying to register a new account; using `atuin register` where `atuin login --2fa` or the server's web UI is the expected path.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

AI-assisted analysis of atuinsh/atuin@900007c480 (2026-09-19). Data as JSON: /api/errors/e5e08e62f3309178. Report an issue: GitHub.

Appendix: source

Thrown at crates/atuin/src/command/client/account/register.rs:93

                        let is_hub_token =
                            auth_type.as_deref() == Some("hub") || session.starts_with("atapi_");

                        if is_hub_token {
                            meta.save_hub_session(&session).await?;
                        } else {
                            meta.save_session(&session).await?;
                            println!(
                                "\nNote: Your account has not been fully migrated to Atuin Hub."
                            );
                            println!(
                                "Sync will continue to work, but you can visit hub.atuin.sh to \
                                 create a new Hub account and link it to your existing CLI \
                                 account."
                            );
                        }
                    }
                    AuthResponse::TwoFactorRequired => {
                        bail!("unexpected two-factor requirement during registration");
                    }
                }

                let _key = paseto_v4::Key::try_load_or_generate(&settings.key_path)?;

                println!(
                    "Registration successful! Please make a note of your key (run 'atuin key') \
                     and keep it safe."
                );
                println!(
                    "You will need it to log in on other devices, and we cannot help recover it \
                     if you lose it."
                );
            } else {
                // Interactive registration: delegate to the browser OAuth flow.
                // Registration on Hub happens on the website; the CLI just needs
                // to authenticate afterwards.
                super::login::Cmd {

View on GitHub (pinned to 900007c480)