badges/shields · error · NotFound

unknown type, provider, or upstream issue

Error message

unknown type, provider, or upstream issue

What it means

ClearlyDefined's API returns HTTP 200 with an empty body when the requested definition type or provider is unknown, which cannot be parsed as JSON. This service detects the empty buffer before the normal JSON parsing flow and throws NotFound with this message.

Source

Thrown at services/clearlydefined/clearlydefined-score.service.js:78

  static render({ score }) {
    score = Math.round(score)
    return {
      label: 'score',
      message: `${score}/100`,
      color: floorCountColor(score, 40, 60, 100),
    }
  }

  async fetch({ type, provider, namespace, name, revision }) {
    const { buffer } = await this._request({
      url: `https://api.clearlydefined.io/definitions/${type}/${provider}/${namespace}/${name}/${revision}`,
      options: { headers: { Accept: 'application/json' } },
    })
    // If the type or provider is not found, the API returns a 200 response
    // with an empty body. It cannot be parsed as JSON, we need to handle this
    // case earlier than in the usual BaseJsonService._requestJson flow.
    if (buffer.length === 0) {
      throw new NotFound({
        prettyMessage: 'unknown type, provider, or upstream issue',
      })
    }
    const json = parseJson(buffer)
    return this.constructor._validate(json, schema)
  }

  async handle({ type, provider, namespace, name, revision }) {
    const data = await this.fetch({ type, provider, namespace, name, revision })
    // Return score only if definition contains some files,
    // else it was an incomplete response due to unknown coordinates
    if (data.described.files > 0) {
      return this.constructor.render({ score: data.scores.effective })
    } else {
      throw new NotFound({
        prettyMessage: 'unknown namespace, name, or revision',
      })
    }

View on GitHub (pinned to 766fd8bc89)

Solutions

  1. Check that the type and provider in the badge URL match ClearlyDefined's supported coordinates (e.g. npm/npmjs, gem/rubygems, maven/mavencentral)
  2. Verify the definition exists at https://clearlydefined.org/ for the given coordinates
  3. Retry later if ClearlyDefined is having an outage producing empty responses
  4. Correct the coordinate path segment order (type/provider/namespace/name/revision)

Example fix

// before
/badge/clearlydefined/score/typo-type/npmjs/lodash/4.17.21
// after
/badge/clearlydefined/score/npm/npmjs/lodash/4.17.21
Defensive patterns

Strategy: validation

Validate before calling

const SUPPORTED = ['npm/npmjs','gem/rubygems','maven/mavencentral','pypi/pypi','github/github','crate/cratesio'];
const coords = `${type}/${provider}`;
if (!SUPPORTED.includes(coords)) throw new Error(`unsupported ClearlyDefined coordinates: ${coords}`);

Type guard

function isNonEmptyBuffer(b) { return Buffer.isBuffer(b) && b.length > 0; }

Try / catch

try {
  const score = await fetchClearlyDefinedScore(type, provider, ns, name, rev);
} catch (e) {
  if (e.status === 404) console.warn('unknown type/provider or upstream issue — verify coordinates on clearlydefined.org');
  else throw e;
}

Prevention

When it happens

Trigger: Calling the clearlydefined score badge with a `type`/`provider` combination (e.g. wrong coordinate path) that the ClearlyDefined API answers with a 200 + empty body instead of 404.

Common situations: Misspelled ecosystem type (e.g. 'npm' vs 'maven' confusion), unsupported provider strings, or ClearlyDefined upstream outages/degradations that yield empty responses.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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