badges/shields · error · NotFound

invalid username

Error message

invalid username

What it means

The Keybase profile service throws NotFound with 'invalid username' when the Keybase API responds with a non-zero status.code, indicating the requested username was rejected by Keybase. The service treats any non-zero API status as 'this user does not exist / name is invalid'.

Source

Thrown at services/keybase/keybase-profile.js:24

  }

  static category = 'social'

  async fetch({ schema, options }) {
    const apiVersion = this.constructor.apiVersion
    // See https://keybase.io/docs/api/1.0/call/user/lookup.
    const url = `https://keybase.io/_/api/${apiVersion}/user/lookup.json`

    return this._requestJson({
      url,
      schema,
      options,
    })
  }

  transform({ data }) {
    if (data.status.code !== 0) {
      throw new NotFound({ prettyMessage: 'invalid username' })
    }

    if (data.them.length === 0 || !data.them[0]) {
      throw new NotFound({ prettyMessage: 'profile not found' })
    }

    return { user: data.them[0] }
  }
}

View on GitHub (pinned to 766fd8bc89)

Solutions

  1. Check the username on keybase.io/<username> and fix the badge URL to the exact current username.
  2. URL-encode any special characters in the username.
  3. If the account was deleted, remove the badge.

Example fix

// before
/keybase/profile/jane.doe
// after (actual Keybase username)
/keybase/profile/janedoe
Defensive patterns

Strategy: validation

Validate before calling

// Verify the username resolves on Keybase before rendering:
const res = await fetch(`https://keybase.io/_/api/1.0/user/lookup.json?username=${encodeURIComponent(username)}`);
const data = await res.json();
if (data.status.code !== 0) throw new Error(`Not a valid Keybase username: ${username}`);

Type guard

function isSuccessfulKeybaseStatus(data) {
  return data && data.status && Number.isInteger(data.status.code) && data.status.code === 0;
}

Try / catch

try {
  profile = await getKeybaseProfileBadge(username);
} catch (e) {
  if (e.name === 'NotFound') {
    renderFallback(`Keybase user '${username}' not found`);
  } else throw e;
}

Prevention

When it happens

Trigger: Requesting /keybase/profile/<username> where the Keybase user lookup API returns status.code !== 0 — typically a nonexistent or malformed username.

Common situations: Typo in the Keybase username in the badge URL; user deleted/renamed their Keybase account; passing an email or proof handle instead of the Keybase username; special characters not URL-encoded.

Related errors

AI-assisted analysis of badges/shields@766fd8bc89 (2026-08-30). Data as JSON: /api/errors/85d1651af159912e. Report an issue: GitHub.