gitbutlerapp/gitbutler · error

Known account is not correctly authenticated. Run

Error message

Known account is not correctly authenticated.
Run '{}' to authenticate with {}.

What it means

This error is thrown by ensure_forge_authentication when a forge account known to GitButler (stored locally) fails a validity check against the forge (GitHub/GitLab/Bitbucket). It means the stored credentials exist but are stale, revoked, or otherwise rejected, so review/merge operations cannot proceed. The library throws it before any forge API call is made to fail fast with an actionable remediation command.

Solutions

  1. Run `but config forge auth` to re-authenticate with the forge
  2. Verify the token is still valid on the forge's developer settings page (GitHub: Settings > Applications; GitLab: Preferences > Access Tokens)
  3. Check that the account has not been removed from the organization or had OAuth grants revoked
  4. Retry the operation after re-authenticating

Example fix

// before
but forge review create ...
// error: Known account is not correctly authenticated.
// after
but config forge auth
but forge review create ...
Defensive patterns

Strategy: try-catch

Validate before calling

// before invoking review/merge ops, check auth state via the CLI
if !but config forge status --check; then
  echo 'run: but config forge auth';
fi

Type guard

function isAuthError(e: Error): boolean {
  return /not correctly authenticated/i.test(e.message);
}

Try / catch

try {
  await runBut(['forge', 'review', 'create']);
} catch (e) {
  if (/not correctly authenticated/.test(e.message)) {
    await runBut(['config', 'forge', 'auth']);
    return retry();
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling enable_auto_merge, set_draftiness, or create_review when ForgeAccountValidity::Invalid is returned for the known account — e.g. after a token was revoked server-side, expired, or the password/credential changed.

Common situations: Developers hit this after rotating a GitHub personal access token, when an organization revoked an OAuth grant, after a long-lived token expired, or when SSO/session policies invalidate stored GitButler credentials.

Understand the failure class

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@58e5313667 (2026-09-18). Data as JSON: /api/errors/24a92ad5b91de5e5. Report an issue: GitHub.

Appendix: source

Thrown at crates/but/src/command/legacy/forge/review.rs:411

            "Unable to determine the forge for this project. Is target branch associated with a supported forge?"
        )
    })?;

    let account_validity =
        but_forge::check_forge_account_is_valid(preferred_forge_user, &forge_repo_info, &storage)
            .await?;

    let forge_display_name = match forge_repo_info.forge {
        but_forge::ForgeName::Azure => {
            anyhow::bail!("Azure is unsupported at the minute. Sorry 😞.");
        }
        but_forge::ForgeName::GitHub => "GitHub",
        but_forge::ForgeName::GitLab => "GitLab",
        but_forge::ForgeName::Bitbucket => "Bitbucket",
    };

    match account_validity {
        but_forge::ForgeAccountValidity::Invalid => Err(anyhow::anyhow!(
            "Known account is not correctly authenticated.\nRun '{}' to authenticate with {}.",
            "but config forge auth",
            forge_display_name
        )),
        but_forge::ForgeAccountValidity::NoCredentials => Err(anyhow::anyhow!(
            "No authenticated forge users found.\nRun '{}' to authenticate with {}.",
            "but config forge auth",
            forge_display_name
        )),
        but_forge::ForgeAccountValidity::Valid => {
            // All good, continue
            Ok(())
        }
    }
}

/// Get list of branch names that don't have PRs yet.
fn get_branches_without_prs(

View on GitHub (pinned to 58e5313667)