Maven Repository Checklist: Fixing “Could not find artifact” in a Real CI Build

ByBNW TEAM

“Could not find artifact” in a CI pipeline is one of those annoying build failures that consumes your time and confidence fast. I’ve debugged dozens of these in the past decade, from flaky local .m2 caches to Artifactory pinned endpoints.

This checklist takes you step by step through what to do when artifacts are missing in a CI environment, and how Maven packages and Maven repository setup connect to your build system.

Quick Recap: Why Artifacts Disappear in CI

Most missing artifact errors have three causes:

  • Wrong coordinates (groupId, artifactId, version)
  • Repository access issues (URL, credentials, proxy)
  • Repository content issues (missing deploy, snapshots vs releases, corrupt metadata)

CI increases the variables because you now have ephemeral build agents, network rules, and cached credentials. The good news is a routine checklist will usually get you back to green quickly.

Checklist for Maven Repositories: What You Must Check in CI

1) Confirm Artifact Coordinates in pom.xml and dependencyManagement

Your groupId, artifactId, and version must exactly match the published artifact.

Common failures include:

  • Typos
  • Trailing spaces
  • Mixing snapshot and release versions

If you’re using dependencyManagement, confirm the version is not being overridden further down the dependency tree.

2) Validate Repository URLs and the settings.xml Used by CI

CI agents often use a different settings.xml than your local machine.

Make sure:

  • The correct repositories are configured in xml
  • The right mirrors are applied
  • You have checked the build’s effective settings

On ephemeral runners, a missing settings.xml can quietly force Maven to use only Maven Central.

3) Check Private Maven Package Credentials and Permissions

If you rely on private Maven packages (GitHub Packages, Nexus, Artifactory), confirm your CI has valid authentication:

  • Token or username/password must have read access
  • Read or download scoped tokens are more secure and often required for CI jobs

4) Inspect Snapshot vs Release Repository Rules

Snapshots and releases are handled differently.

Typical issues:

  • Release repository endpoint does not allow snapshots
  • Artifact is a snapshot, but the repository is configured as release-only
  • Artifact is a release, but you are pointing to a snapshots repo

Match the repository type to the artifact lifecycle.

5) Inspect Repository Metadata and Checksums

Corrupt maven-metadata.xml or bad checksums can block resolution.

Actions:

  • If you own the repository: reindex or re-upload the artifact
  • If it’s a proxy repository: clear its cache and refetch from upstream

6) Reproduce CI Resolution Locally Using CI Settings

To mimic the CI environment locally, run:

  • mvn -s path/to/ci-settings.xml dependency:resolve -X

The debug log will show:

  • Which URL Maven attempted
  • Which repository it selected
  • Why it failed (auth, missing metadata, wrong repo, etc.)

7) Confirm CI Network and Proxy Rules Allow Host Access

CI runners may sit behind:

  • Corporate proxies
  • Restricted VPC rules
  • Firewall policies

Make sure the build agent can reach:

8) Purge CI Agent Caches and Local Repo When Needed

Stale or incomplete downloads in the agent’s local .m2 can cause repeated failures.

Fix options:

  • Clear cache
  • Use a fresh workspace
  • Force Maven to download again

Deep Dive Comparisons: Maven Central, Private Repositories, and Maven Packages

Maven Central

  • Lowest friction
  • High availability
  • No auth required in most cases
  • Public releases only

Private Repositories (Nexus, Artifactory)

  • Fine-grained control
  • Staging and promotion workflows
  • Fast local caching
  • Requires credentials and admin overhead

GitHub Packages and Other “Maven Packages” Options

  • Works well with SCM and CI workflows
  • Adds complexity around:
    • Token scope
    • Package visibility
    • Organization permissions

For CI, prefer proxying Maven Central through an internal repo so you have a consistent and auditable dependency source and less risk from external outages.

Real CI Tip From Experience

For a flaky build, my first step is to confirm whether the build agent changes between runs. Flaky failures are often caused by network issues or regional events.

To stabilize:

  • Pin builds to a stable runner region
  • Use a hosted mirror in your private repository to normalize the environment

Conclusion: A Practical Approach to Fixing “Could not find artifact”

Start by verifying coordinates, then check settings.xml, credentials, and network access.

Next:

  • Reproduce locally using the same CI settings
  • Inspect repository metadata
  • Clear caches when needed

Long-term reliability comes from proxying external repositories through an internal Nexus or Artifactory and using scoped tokens for Maven packages. These practices turn random “Could not find artifact” failures into manageable, fixable issues.

FAQs

What should I check first when I see “Could not find artifact” in CI from Maven?

First, confirm dependency coordinates (groupId, artifactId, version) match the published artifact. Then verify the CI agent’s settings.xml and repository URLs are correct. Many failures come down to typos or missing settings.

How do I know whether a repository needs credentials or a token?

Private Maven repositories and systems like GitHub Packages require authentication. Check the repository configuration in settings.xml and CI logs. A 401 or 403 HTTP error during resolution usually indicates missing or invalid credentials.

Can snapshots be resolved from release repositories?

No. Releases and snapshots are handled separately. If you specify a -SNAPSHOT artifact, Maven expects snapshots to be enabled for that repository. Trying to resolve a snapshot from a release-only repository will fail.

Why does clearing the .m2 cache help?

Broken or partial downloads can leave corrupted files or bad metadata in the cache. Clearing .m2 forces a clean download and validation, which can fix checksum or metadata-related failures.

When should you use Maven Central vs a private repository for CI?

For stability and control, proxy Maven Central through a private repository (Nexus or Artifactory). This adds caching, internal auditing, and a place to host private Maven packages while still consuming public dependencies reliably.

Similar Posts