What causes "invalid alias" in badges/shields?

Print and inspect the alias value; count the colon-separated segments — it must split into 1, 2, or 3 parts.

badges/shields · error · InvalidParameter

invalid alias

Error message

invalid alias

What it means

This error is thrown by the Matrix service's fetch() when an alias string cannot be parsed into a valid host. Aliases are split on ':' and must yield 1-3 parts; any other segment count falls into the default branch and throws InvalidParameter with 'invalid alias'. It indicates the caller supplied a malformed alias identifier (e.g. a room or user alias) that does not conform to the expected #alias:host or #alias:host:port style shapes.

Source

Thrown at services/matrix/matrix.service.js:233

        ).length
      : 0
  }

  async fetch({ roomAlias, serverFQDN, fetchMode }) {
    let host
    if (serverFQDN === undefined) {
      const splitAlias = roomAlias.split(':')
      // A room alias can either be in the form #localpart:server or
      // #localpart:server:port.
      switch (splitAlias.length) {
        case 2:
          host = splitAlias[1]
          break
        case 3:
          host = `${splitAlias[1]}:${splitAlias[2]}`
          break
        default:
          throw new InvalidParameter({ prettyMessage: 'invalid alias' })
      }
    } else {
      host = serverFQDN
    }
    if (host.toLowerCase() === 'matrix.org' || fetchMode === 'summary') {
      // summary endpoint (default for matrix.org)
      return await this.fetchSummary({ host, roomAlias })
    } else {
      // guest access
      return await this.fetchGuest({ host, roomAlias })
    }
  }

  async handle({ roomAlias }, { server_fqdn: serverFQDN, fetchMode }) {
    const members = await this.fetch({ roomAlias, serverFQDN, fetchMode })
    return this.constructor.render({ members })
  }
}

View on GitHub (pinned to 766fd8bc89)

Solutions

Print and inspect the alias value; count the colon-separated segments — it must split into 1, 2, or 3 parts.
Strip URL prefixes/encoding: use the raw alias like '#room:example.org', not 'https://matrix.to/#/%23room%3Aexample.org'.
Remove any trailing/extra colons or port suffixes from the alias before calling.
If no alias is needed, pass the server FQDN instead so the else branch (host = serverFQDN) is used.

Example fix

// before
const res = await matrixService.fetch({ alias: 'https://matrix.to/#/%23room%3Aexample.org' })
// after
const alias = decodeURIComponent('https://matrix.to/#/%23room%3Aexample.org'.split('/#/')[1]).replace(/:$/, '')
const res = await matrixService.fetch({ alias })

Defensive patterns

Strategy: validation

Validate before calling

function isValidAlias(alias) {
  if (typeof alias !== 'string') return false
  const parts = alias.split(':')
  return parts.length >= 1 && parts.length <= 3 && parts.every(p => p.length > 0)
}
if (!isValidAlias(alias)) throw new Error(`invalid alias: ${alias}`)

Type guard

function isAlias(v) {
  return typeof v === 'string' && /^[^:]+(:[^:]+){0,2}$/.test(v)
}

Try / catch

try {
  const data = await matrixService.fetch({ alias })
} catch (err) {
  if (err && err.prettyMessage === 'invalid alias') {
    throw new Error(`Alias '${alias}' is malformed; use #name:host form`)
  }
  throw err
}

Prevention

Validate alias shape (1-3 colon-separated non-empty segments) before calling fetch.
Pass decoded raw aliases, never full matrix.to URLs or percent-encoded strings.
Trim whitespace and strip stray trailing colons from user-supplied input.
Prefer server FQDN input when an alias is not actually needed.

When it happens

Trigger: Calling fetch (directly or via members) with an alias containing the delimiter ':' but producing 0, 4 or more split segments, e.g. '#room:a:b:c' or an empty string containing stray colons.

Common situations: Passing a full matrix.to URL instead of an alias, including an encoded or copy-pasted alias with extra colons (port or escape sequences), or handing the service an empty/whitespace alias with delimiters.

Related errors

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