badges/shields · error · NotFound

unknown namespace, name, or revision

Error message

unknown namespace, name, or revision

What it means

The ClearlyDefined score service returns data only when the definition describes at least one file (data.described.files > 0). If fetch succeeded but the payload is effectively empty, the coordinates (namespace, name, or revision) are considered unknown and NotFound is thrown.

Source

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

    // 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. Verify the definition on clearlydefined.org and confirm it has harvested file data
  2. Double-check the revision format expected for the ecosystem (e.g. exact version string as listed)
  3. Retry after some time so ClearlyDefined can harvest the definition
  4. Fix the namespace segment (e.g. include the Maven groupId or GitHub org where required)

Example fix

// before
/badge/clearlydefined/score/npm/npmjs/lodash/not-a-version
// after
/badge/clearlydefined/score/npm/npmjs/lodash/4.17.21
Defensive patterns

Strategy: validation

Validate before calling

// ensure revision and namespace match the definition listed on clearlydefined.org
if (!revision || revision.includes(' ')) throw new Error('revision required and must match the published version exactly');

Type guard

function isHarvested(def) { return def && def.described && Number(def.described.files) > 0; }

Try / catch

try {
  const score = await fetchScore(type, provider, ns, name, rev);
} catch (e) {
  if (e.status === 404 && e.message.includes('unknown namespace')) retryAfterHarvestDelay();
  else throw e;
}

Prevention

When it happens

Trigger: Requesting a score for coordinates whose definition has described.files === 0 — i.e. the revision was never harvested, or namespace/name/revision do not exist in ClearlyDefined.

Common situations: Newly published packages not yet harvested by ClearlyDefined, wrong revision string (e.g. missing 'v' prefix conventions), wrong namespace (e.g. missing Maven group), or typos in package names.

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/4005e6807b2b35be. Report an issue: GitHub.