usebruno/bruno · error · Error

Username is required for OAuth2 password credentials flow

Error message

Username is required for OAuth2 password credentials flow

What it means

Thrown by fetchTokenPassword when oauth2Config.username is falsy. The password grant exchanges the resource owner's credentials for a token, so a username is mandatory. The helper checks it before building the form body.

Source

Thrown at packages/bruno-requests/src/auth/oauth2-helper.ts:219

 */
const fetchTokenPassword = async (oauth2Config: OAuth2Config, axiosInstance?: AxiosInstance) => {
  const {
    accessTokenUrl,
    clientId,
    clientSecret,
    username,
    password,
    scope,
    credentialsPlacement = 'basic_auth_header',
    additionalParameters
  } = oauth2Config;

  if (!accessTokenUrl) {
    throw new Error('Access Token URL is required for OAuth2 password credentials flow');
  }

  if (!username) {
    throw new Error('Username is required for OAuth2 password credentials flow');
  }

  if (!password) {
    throw new Error('Password is required for OAuth2 password credentials flow');
  }

  if (!clientId) {
    throw new Error('Client ID is required for OAuth2 password credentials flow');
  }

  const requestConfig: RequestConfig = {
    method: 'POST',
    url: accessTokenUrl,
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Accept': 'application/json'
    },
    data: '',

View on GitHub (pinned to 9bdd81c7bd)

Solutions

Pass a non-empty username in the OAuth2Config.
If the username comes from user input, validate the field is non-empty before triggering the token request.
Confirm the grant type is actually what you want — machine-to-machine calls should use client_credentials, not password.

Example fix

// before
const config = { grantType: 'password', accessTokenUrl: url, password: pass, clientId: id };

// after
const config = {
  grantType: 'password',
  accessTokenUrl: url,
  username: formUsername,
  password: pass,
  clientId: id
};

Defensive patterns

Strategy: validation

Validate before calling

if (!config.username || !config.username.trim()) throw new Error('Username required for password grant');

Type guard

function hasUsername(c) { return typeof c.username === 'string' && c.username.trim().length > 0; }

Try / catch

try { await getOAuth2AccessToken(config, tokenStore); }
catch (e) { if (e.message.includes('Username is required')) { /* prompt user */ } else throw e; }

Prevention

Treat username as required form input with non-empty validation on the client.
Confirm grant type selection before requiring username — client_credentials does not need it.

When it happens

Trigger: getOAuth2AccessToken called with grantType='password', a valid accessTokenUrl, but no username supplied (empty string, null, or undefined).

Common situations: End-user login form submitted with an empty username; config loaded from a session where the user field was never populated; programmatic caller passed an object missing the username key.

Related errors

AI-assisted analysis of usebruno/bruno@9bdd81c7bd (2026-08-13). Data as JSON: /api/errors/5e05f8dddcdd9ea9. Report an issue: GitHub.