Troubleshooting

What the Maven endpoint answers, what each answer means, and what to do about it. Your build tool usually prints the status and the message that Artifex returned.

401 Unauthorized

Sign in with a personal access token to access this repository.

The request carried no credentials, or the token was revoked, expired, or made for another product, and the repository needs credentials for what was asked.

Do the following:

1. Check that your client is sending credentials. For Maven, the id of the server in settings.xml has to match the id of the repository. For Gradle, the properties have to be named after the repository.
2. Check that the token is an Artifex token and hasn't been revoked, on the Personal access tokens page in CodeSoh Accounts.
3. Check that the token hasn't expired.

A public repository answers 401 for a deploy with no credentials, because writing always needs a token.

403 Forbidden

You don't have permission to do that in this repository.

The credentials were recognized, and they aren't enough for what was asked.

Do the following:

1. If the credentials are a token, check that it's been granted access to this repository. A token reaches nothing until it's granted, including in repositories that you own. See Tokens in Artifex.
2. Check that the grant is Write if you're deploying.
3. Check that you hold the permission that you granted the token. A token never reaches more than its owner.

Other 403 answers come from the repository's settings:

Message	Meaning
This repository doesn't accept snapshot versions.	Allow snapshots is off. See Snapshots.
This repository doesn't allow deleting files.	Allow deleting files is off. See Immutability.
The index is generated by the repository and can't be uploaded.	Something tried to deploy under .index/. See The Maven index.

404 Not Found

Message	Meaning
No repository at this address.	The owner handle or the URL name in the address is wrong, or the repository was deleted or renamed.
Directory listings aren't available. Request a file.	The request was for a directory. Use the repository pages.
This path isn't part of the Maven repository layout.	The path doesn't name an artifact or a maven-metadata.xml.
Upload the file before its checksum.	A .sha1 or similar was deployed before the file it belongs to.
Not found.	The repository doesn't hold the file, and no upstream that could answer has it.

A private repository that you can't read looks the same as one that doesn't exist, so 404 from the pages can also mean that you haven't been given access.

409 Conflict

Message	Meaning
This release file already exists. Releases can't be replaced.	The path already holds a file, and Allow replacing files is off. Publish a new version, or turn the setting on. See Immutability.
This snapshot build already exists. Deploy again to create a new build.	The same timestamped snapshot build was deployed twice. Deploy again; your client produces a new timestamp. See Snapshots.

400 Bad Request

Message	Meaning
The uploaded ALGORITHM checksum doesn't match the file. Expected DIGEST.	The bytes that arrived don't match the checksum that the client uploaded. The upload was corrupted; run the deploy again.
The ALGORITHM checksum file isn't a hex digest.	The checksum file's body isn't a digest.
The metadata document isn't well-formed.	An uploaded maven-metadata.xml isn't valid XML.
The metadata names build T-B, but the newest deployed build is T-B.	The uploaded snapshot metadata names a build other than the newest deployed one. Deploy the files before the metadata.
The file name's version doesn't match its directory.	A release file's name carries a version other than the directory's.
This path isn't part of the Maven repository layout.	The deployed path doesn't follow the layout.

413 Payload Too Large

Files larger than 4 GiB can't be deployed.

See Limits.

503 Service Unavailable

The repository can't answer right now, and the request may work later. The response carries Retry-After.

Message	Meaning
NAME answered STATUS.	An upstream returned an error status.
NAME didn't answer within N ms.	An upstream didn't start answering within its timeout. Raise the timeout, or check whether the upstream is reachable.
NAME couldn't be reached.	An upstream couldn't be contacted at all. Check its URL.
NAME sent a file whose ALGORITHM checksum doesn't match its content.	An upstream's own checksum disagrees with the bytes it sent. The file isn't kept.
NAME sent no body.	An upstream answered without content.
The file's bytes can't be located. or The file's bytes are missing. Try again later.	The repository's record of the file is there and its bytes aren't reachable. Try again; if it continues, deploy the file again.

A 503 means unavailable, not missing. A dependency that answers 503 exists as far as Artifex knows. For how upstreams tell the two apart, see Upstream repositories.

405 Method Not Allowed

Method not allowed.

The Maven endpoint accepts GET, HEAD, PUT, and DELETE.

416 Range Not Satisfiable

The request asked for a byte range outside the file. The response carries the file's size in Content-Range. Let the client download the file from the start.

Builds that resolve the wrong bytes

If a build gets an older file than you expect, check the following:

• The repository's generated metadata, at GROUP/ARTIFACT/maven-metadata.xml, which is what the client reads for version lists.
• The file page, which says whether the file was deployed here or cached from an upstream, and which upstream it came from.
• The activity, which records replacements with the digest of the file that was there before.