badges/shields · error · NotFound

artifact or ${versionType}version not found

Error message

artifact or ${versionType}version not found

What it means

Thrown by the Nexus service's transform() when the Nexus search API returns zero items, meaning no artifact matching repo/package (and version constraints) exists. For snapshot repositories (`repo === 's'`) the message reads 'artifact or snapshot version not found', otherwise 'artifact or version not found'. It is a NotFound, so it renders as the badge's 'not found' state rather than an upstream/server error.

Source

Thrown at services/nexus/nexus.service.js:155

    const json = await this._requestJson(
      this.authHelper.withBasicAuth({
        schema: searchApiSchema,
        url,
        options: { searchParams },
        httpErrors: {
          404: 'artifact not found',
        },
      }),
    )

    return { json }
  }

  transform({ repo, json }) {
    if (json.items.length === 0) {
      const versionType = repo === 's' ? 'snapshot ' : ''
      throw new NotFound({
        prettyMessage: `artifact or ${versionType}version not found`,
      })
    }
    return { version: json.items[0].version }
  }

  async handle({ repo, groupId, artifactId }, { server, queryOpt }) {
    const { json } = await this.fetch({
      repo,
      server,
      groupId,
      artifactId,
      queryOpt,
    })

    const { version } = this.transform({ repo, json })
    return renderVersionBadge({ version })
  }

View on GitHub (pinned to 766fd8bc89)

Solutions

  1. Verify the artifact exists in the target Nexus repository via its search UI or /service/rest/v1/search
  2. Confirm you are passing the correct repo parameter ('s' for snapshots, 'r' for releases)
  3. Check the package name/groupId:artifactId spelling and URL-encoding
  4. Relax any version filter/prefix so at least one version matches

Example fix

// before
/nexus/s/my.group/wrong-artifact.svg
// after
/nexus/s/my.group/correct-artifact.svg  (artifact published to the snapshot repo)
Defensive patterns

Strategy: fallback

Validate before calling

// Pre-check existence via Nexus search API before rendering
const res = await fetch(`${nexusUrl}/service/rest/v1/search?repository=${repo}&maven.group=${group}&maven.artifactId=${artifact}`)
const { items } = await res.json()
if (!items || items.length === 0) throw new Error(`artifact not found in repo ${repo}`)

Type guard

function hasResults(json) {
  return json != null && Array.isArray(json.items) && json.items.length > 0
}

Try / catch

try {
  return await nexusBadge({ repo, pkg })
} catch (e) {
  if (e instanceof NotFound && /not found$/.test(e.message)) {
    return renderPlaceholderBadge('artifact not found')
  }
  throw e
}

Prevention

When it happens

Trigger: Querying a Nexus 3 search endpoint for a package name that does not exist in the repo; requesting a release version from a snapshot repo or vice versa; a version filter that matches nothing; wrong repository id ('s' vs 'r') for the artifact.

Common situations: Typo'd groupId/artifactId; artifact published only as snapshots but queried with the release repo parameter; Nexus instance migrated and repository IDs changed; private repo without the artifact.

Related errors

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