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

Error message

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

What it means

Thrown by the `but forge review` flow after it resolves the repo's forge (GitHub/GitLab/Bitbucket) and checks the stored account. `ForgeAccountValidity::Invalid` means a forge user is on record for the remote but its credentials no longer pass validation, so the command refuses to continue instead of making unauthenticated forge API calls. The message embeds the exact remediation: run `but config forge auth`. (Azure hits a separate, earlier bail in the same match.)

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

Solutions

Run `but config forge auth` and complete authentication for the forge named in the message
If auth keeps failing, verify in the forge's settings that the token still exists and has the required scopes
Check the repo's remote URL points at the forge/account you intended (fork vs upstream mismatch)
Re-run `but forge review` once validity reports Valid

Example fix

# before
but forge review
# error: Known account is not correctly authenticated.
# Run 'but config forge auth' to authenticate with GitHub.

# after
but config forge auth
but forge review

Defensive patterns

Strategy: validation

Validate before calling

# Refresh forge credentials before any review/publish automation
but config forge auth
# then run the review flow; validity is checked inside it and fails fast with the fix named

Type guard

fn forge_account_usable(v: &but_forge::ForgeAccountValidity) -> bool {
    matches!(v, but_forge::ForgeAccountValidity::Valid)
}

Try / catch

// CLI-level: detect the auth failure and route to re-auth
let out = Command::new("but").args(["forge", "review"]).output()?;
if !out.status.success()
    && String::from_utf8_lossy(&out.stderr).contains("not correctly authenticated")
{
    eprintln!("run `but config forge auth`, then retry");
}

Prevention

Re-authenticate before starting long review or publish sessions
Rotate forge tokens on a schedule and re-run `but config forge auth` after every rotation
Keep one forge account per remote URL so validity checks hit the right user
In CI, run auth as an explicit setup step and fail fast on its exit code

When it happens

Trigger: Running `but forge review` or its publish flow when the saved forge token is expired, revoked, or otherwise rejected; the account-validity lookup returns `Invalid` and the match arm builds this anyhow error with the forge display name.

Common situations: Expired GitHub PAT or GitLab token after a rotation window; token revoked from the forge's settings page; org SSO/SAML access removed; credential store restored from an old machine; long-lived CI container with stale auth.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@caf1f223d3 (2026-08-20). Data as JSON: /api/errors/24a92ad5b91de5e5. Report an issue: GitHub.