JFrog Artifactory — Production Administration, Errors and Mistakes

How Artifactory stores binaries, why disks fill and garbage collection does not free them, how to build dev-to-prod promotion and immutable Docker tags, and how to recover from the errors and mistakes seen in production.

Overview

Artifactory sits in the middle of every build and every deploy. When it fails, builds stop publishing, pipelines stop resolving dependencies, and Kubernetes cannot pull images. Most production incidents fall into a few groups: the filestore fills up, deletes do not free space, a permission is too narrow (deploys fail) or too wide (releases get overwritten), an upstream registry goes away, or someone deletes, overwrites or promotes the wrong thing.

The one idea to keep: Artifactory stores each binary once, by checksum, and keeps paths as database rows. Deleting a path removes a row. The bytes leave the disk only when no other path points at that checksum, the trash can has let go of it, and garbage collection has run. Almost every storage question in an interview comes back to that chain.

> [!NOTE] > Editions matter. JFrog Container Registry (JCR) covers Docker, Helm, OCI and Generic packages. Many REST operations used below (Move Item, Set Item Properties, Restore from Trash Can) are documented as requiring Artifactory Pro. Build promotion is listed from Pro X. High availability and Federated repositories need Enterprise X or Enterprise+. Package cleanup policies need Enterprise X or Enterprise+.

Symptom to first command

Builds fail to publish with 413 — curl -s -H "Authorization: Bearer $TOKEN" "$ART_URL/artifactory/api/storageinfo" — Storage full, quotas and GC
Disk did not shrink after deleting artifacts — grep Storage garbage collector report in artifactory-service.log — Storage full, quotas and GC
Deploy returns 403 for an existing version — Check the deployer's Delete/Overwrite permission on the repo — Deploy and resolve errors
Deploy returns 409 — Read the response body: checksum or POM consistency — Deploy and resolve errors
Remote dependency returns 404 that exists upstream — Check Deploy/Cache on the remote repo, then artifactory-request-out.log — Deploy and resolve errors
A Docker tag points at a different image than yesterday — Check Tag Retention and Enforce Strict Tag Overwrite on the repo — Docker tags in Artifactory
A repository or artifact was deleted — Open the Trash Can (14-day default retention) — Mistakes
AQL returns 429 or 408 — Lower concurrency, add the stream: true header, narrow the query — Administration toolkit

What you will be able to do

Explain local, remote, virtual and Federated repositories, checksum-based storage and the filestore chain, and which edition each feature needs.
Run a disk-full incident: find what is filling the disk, free space safely, and know why a delete does not shrink the disk until the trash can and garbage collection let go.
Design dev, QA and prod repositories with permissions so CI can only write to dev and only a promotion identity can write to prod.
Configure Docker repositories so a tag cannot be silently overwritten, and roll back by digest.
Diagnose 401, 403, 404, 409 and 413 responses, checksum mismatches and remote repository outages.
Recover from deleted repositories, overwritten releases and over-eager cleanup, and put guardrails in place.

Key concepts

Checksum-based storage: Each binary is stored once by checksum; repository paths are database rows pointing at it, so copy, move and delete are database transactions.
Local, remote, virtual, Federated: Deployed artifacts, a caching proxy of an upstream source, one URL over several repositories, and a local repository mirrored across JPDs (Enterprise X or Enterprise+).
Filestore and binary provider chain: Where bytes live, configured in binarystore.xml: file-system, cache-fs, S3, Azure, Google or cluster templates.
Trash Can: Holds items deleted from local repositories for the retention period, 14 days by default, so they can be restored.
Garbage collection: Runs every 4 hours by default; the small GC removes expired trash, the full GC (every 20th run) removes all unreferenced binaries.
Storage quota: A disk usage percentage above which deploys get 413 and Datastore disk space is too high, with a lower warning level.
Delete/Overwrite permission: Required to delete or overwrite an existing path; withholding it from deployers makes releases write-once.
Build promotion: POST /api/build/promote/{buildName}/{buildNumber}: sets build status and moves or copies its artifacts to a target repository; needs Deploy permission on the build.
Docker Tag Retention and Max Unique Tags: Retention keeps overwritten tags under their SHA2; Max Unique Tags caps distinct tags with FIFO removal and wins when the two conflict.
Enforce Strict Tag Overwrite: Docker and OCI setting, enabled by default, that requires Delete/Overwrite to push an existing name and tag.

When to use it

Use this page when you run or design an Artifactory instance that CI pipelines and production deploys depend on.
Use it during a storage incident: builds failing with 413, a filling filestore, or deletes that do not shrink the disk.
Use it when designing dev, QA and prod repositories and the permissions and promotion flow between them.
Use it when Docker tags must be trustworthy for rollbacks and Kubernetes deployments.
Use it to prepare for platform, DevOps and SRE interviews that ask about artifact management in production.

Interview questions

Let's say your Artifactory instance file store hits 95% capacity on a weekend with no on-call engineer immediately available. And new builds start failing to publish. What's the fastest safe mitigation and what do you check before doing it?
A build pipeline needs to publish a release artifact to production only after it passes QA sign off, but sign off happens manually sometimes days after the build. How do you structure the Artifactory repos and flow so a partially tested artifact can never accidentally reach the prod?
A Docker image tag myapp:latest was overwritten in Artifactory and now a rollback to previous version is impossible. How should the repo have been configured to prevent this?
Builds fail with 413 Request Entity Too Large. Is Artifactory full?
You deleted 2 TB of old snapshots but the disk usage did not move. Why, and what do you do?
Someone deleted a production repository. How do you recover, and how do you stop it happening again?
A pipeline gets 403 when deploying, and another gets 404 from a remote repository for a package that exists upstream. What is going on?
An upstream registry is down and builds that depend on it fail. What can Artifactory do for you?
Clients report a checksum mismatch, or deploys fail with 409. How do you debug it?
A cleanup policy deleted artifacts a team still needed. How should cleanup be set up?
AQL queries are slow, return 429 or 408, and the database is under pressure. What do you change?
How would you audit an Artifactory instance for over-broad access?