[BUG] Helm Chart and Docker image can't share same name/version combo in a given store

[slik13]

Environmental Info:

Linux PC 5.15.167.4-microsoft-standard-WSL2 #1 SMP Tue Nov 5 00:21:55 UTC 2024 x86_64 x86_64 x86_64 GNU/Linux

Hauler Version:

__ __ ___ __ __ __ _______ .______
| | | | / \ | | | | | | | || _
| || | / ^ \ | | | | | | | | | |) |
| __ | / /\ \ | | | | | | | | | /
| | | | / _____ \ | --' | | ----.| | | |\ ----.
|| || // __\ _/ ||||| _| `.__|
hauler: Airgap Swiss Army Knife

GitVersion: 1.2.0
GitCommit: 7d28df1
GitTreeState: clean
BuildDate: 2025-02-07T00:04:35Z
GoVersion: go1.23.5 X:boringcrypto
Compiler: gc
Platform: linux/amd64

Describe the Bug:

When a store is created and I add both a chart and an image that have the same name and version (both using a manifest and directly doing 'add'), the last artifact that is added crushes the first one. When 'store info' is run we only see the last artifact that was added.

If you inpect the index.json file in the store during the second add, it will actually temporarily hold both artifacts properly, but there appears to be a final cleanup action that removes one of the entries.

Steps to Reproduce:

Any manifest that contains both a chart and a docker image of the same name and version. It's critical that the docker image doesn't contain a subpath in it's name, so the manifests end up like:

"annotations": {
            "kind": "dev.cosignproject.cosign/image",
            "org.opencontainers.image.ref.name": "hauler/my-project:4.1.1"
         },
...
"annotations": {
            "io.containerd.image.name": "my-artifactory.com/my-project:4.0.1",
            "kind": "dev.cosignproject.cosign/image",
            "org.opencontainers.image.ref.name": "my-project:4.1.1"
         }

Expected Behavior:

We should be able to add charts and images that have the same name and version. These are two different types of artifacts.

Actual Behavior:

The last artifact to be added is the only one in the store.

Additional Context:

This might be an issue with the underlying ORAS library, I haven't investigated this too thoroughly yet.

[zackbradys]

Hey @slik13, thank you for opening this issue and providing some context and background on it.

We have part of this covered and mentioned in our docs under https://docs.hauler.dev/docs/known-limits#limitations, but it doesn't fully cover overlapping artifact names and I'm surprised we didn't already have an issue opened for it. I'm not sure when we would be able to get around to implementing a fix for it, but we will keep this open until we have more information!

[hdsakatti]

Hi @zackbradys
We're currently working on setting up an air-gapped registry and file server with Hauler in our environment, and we've encountered this exact limitation.
Our use case involves several components where the Helm chart and container image purposely share the same name and version for consistency.

While temporary workarounds may exist (modifying names or versions ), these approaches complicate our automation and deployment pipelines. They also require us to maintain additional mapping logic between the modified names and their original counterparts.

Would it be possible to prioritise this issue in the upcoming release?

Thank you for your consideration!

[ChrisLay3]

Local Solution to Prevent Images and Charts from Clobbering in OCI Store:
I encountered the same issue where images and charts with the same name and version would overwrite each other in the OCI store due to identical reference paths.
I was able to solve this locally by introducing type-based namespacing for charts and files while leaving images at the root level.

Summary of Changes

1. Type-Prefixed References for Charts and Files
   I modified AddOCI and AddOCICollection to accept an additional kind parameter (Images, Charts, Files).

Introduced a utility function namespaceRefByKind that prepends a namespace prefix (charts/, files/) to the reference before adding it to the OCI index.

This ensures:

Charts are stored under charts/:.

Files are stored under files/:.

2. Patched Handlers for Charts and Files
   Updated all relevant calls to AddOCI and AddOCICollection across the codebase (sync.go, add.go, etc.) to pass the appropriate kind.

Adjusted test cases (store_test.go) to reflect the updated function signatures.

3. Images Left Unchanged (Stored as :)
   Images remain unprefixed and continue using the standard reference path (:).

This works because charts and files are now explicitly namespaced, preventing any collision even if the image name matches the chart name.

Why This Works
Previously, both charts and images were added to the store using the same reference format (:), causing collisions.
By explicitly prefixing only charts and files (charts/:, files/:), while leaving images unprefixed (:), the store now treats them as separate namespaces at the reference level.
This resolves the collision issue while keeping image workflows (storeImage and cosign.SaveImage) untouched.

This solution is clean, minimally invasive, and leverages existing store behaviors while ensuring logical separation of content types in the store index.

Reference PR (for illustration purposes only)
I modeled my approach based on the proposal in this PR:
#439

[slik13]

This does appear to solve the issue testing with a local build.

@zackbradys Is this something that could be included in the next release?

[Shoelace]

I have just hit this issue using hauler 1.3.1.

my current work around is to have multiple stores
ie: store_images and store_charts
eg (not actual commands.. just the idea )
hauler store -s store_images add image my_helm_app:0.0.0
hauler store -s store_charts add chart my_helm_app --version 0.0.0

that said a proper fix would be better

[Shoelace]

Okay.. so i just tried this with hauler 1.4.0. using path rewrite ( #475 )

i can get a chart and an image in a store with the same name/version BUT only if i do a rewrite on both of them.

i was able to do it both manually (hauler store add chart --rewrite .... and hauler store add image --rewrite ... ) and via a manifest file (with rewrite attributes) using hauler store sync

this does not work if i do hauler store add chart --add-images ....
the image ends up clobbering the chart

If you need an example i can try and put one together..

so i think more work is required.. or atleast to get these 2 features to work together better

[zackbradys]

Hey @Shoelace, thanks for already giving v1.4.0 a test and specifically with some of the new features!!!

If you could put an example together, maybe the full commands and their full outputs, then we can look at finding a way to address it. You should be able to use --add-images, --add-dependencies, and --rewrite in the CLI or in a manifest.

Let us know!!! Thank you in advance!

[Shoelace]

I have anonymised the ips.. i hope that wont change anything

 __    __       ___       __    __   __       _______ .______
|  |  |  |     /   \     |  |  |  | |  |     |   ____||   _  \
|  |__|  |    /  ^  \    |  |  |  | |  |     |  |__   |  |_)  |
|   __   |   /  /_\  \   |  |  |  | |  |     |   __|  |      /
|  |  |  |  /  _____  \  |  `--'  | |  `----.|  |____ |  |\  \----.
|__|  |__| /__/     \__\  \______/  |_______||_______|| _| `._____|
hauler: Airgap Swiss Army Knife

GitVersion:    v1.4.2-dev.1
GitCommit:     e8a5f82
GitTreeState:  clean
BuildDate:     2026-01-22T15:34:29Z
GoVersion:     go1.25.5 X:boringcrypto
Compiler:      gc
Platform:      linux/amd64
$ rm -rf store/                                                                                                               $ hauler -l debug store add chart track-line-diagram --repo  http://x.x.x.x/repository/helm
2026-01-29 16:41:45 DBG running cli command [hauler store add chart]
2026-01-29 16:41:45 DBG using store at [/home/user/store]
2026-01-29 16:41:45 INF adding chart [track-line-diagram] to the store
2026-01-29 16:41:46 INF successfully added chart [track-line-diagram:1.83.0]
2026-01-29 16:41:46 DBG extracting chart archive [track-line-diagram-1.83.0.tgz]
$ hauler store info
+----------------------------------+-------+----------+----------+--------+
| REFERENCE                        | TYPE  | PLATFORM | # LAYERS | SIZE   |
+----------------------------------+-------+----------+----------+--------+
| hauler/track-line-diagram:1.83.0 | chart | -        |        1 | 2.9 MB |
+----------------------------------+-------+----------+----------+--------+
|                                                        TOTAL   | 2.9 MB |
+----------------------------------+-------+----------+----------+--------+
$ hauler -l debug store add image x.x.x.x:8082/track-line-diagram:1.83.0                                                
2026-01-29 16:42:17 DBG running cli command [hauler store add image]
2026-01-29 16:42:17 DBG using store at [/home/user/store]
2026-01-29 16:42:17 INF adding image [x.x.x.x:8082/track-line-diagram:1.83.0] to the store
2026-01-29 16:42:18 DBG multi-arch image [false]
2026-01-29 16:42:32 INF successfully added image [x.x.x.x:8082/track-line-diagram:1.83.0]
$ hauler store info
+----------------------------------------------+-------+-------------+----------+--------+
| REFERENCE                                    | TYPE  | PLATFORM    | # LAYERS | SIZE   |
+----------------------------------------------+-------+-------------+----------+--------+
|       x.x.x.x:8082/track-line-diagram:1.83.0 | image | linux/amd64 |       11 | 8.5 MB |
+----------------------------------------------+-------+-------------+----------+--------+
|                                                                       TOTAL   | 8.5 MB |
+----------------------------------------------+-------+-------------+----------+--------+
$ hauler -l debug store add chart track-line-diagram --repo  http://x.x.x.x/repository/helm --rewrite helm/track-line-diagram:1.83.0
2026-01-29 16:43:22 DBG running cli command [hauler store add chart]
2026-01-29 16:43:22 DBG using store at [/home/user/store]
2026-01-29 16:43:22 INF adding chart [track-line-diagram] to the store
2026-01-29 16:43:23 INF successfully added chart [track-line-diagram:1.83.0]
2026-01-29 16:43:23 DBG extracting chart archive [track-line-diagram-1.83.0.tgz]
$ hauler store info
+--------------------------------+-------+----------+----------+--------+
| REFERENCE                      | TYPE  | PLATFORM | # LAYERS | SIZE   |
+--------------------------------+-------+----------+----------+--------+
| helm/track-line-diagram:1.83.0 | chart | -        |        1 | 2.9 MB |
+--------------------------------+-------+----------+----------+--------+
|                                                      TOTAL   | 2.9 MB |
+--------------------------------+-------+----------+----------+--------+
$ hauler -l debug store add image x.x.x.x:8082/track-line-diagram:1.83.0 --rewrite nexus/track-line-diagram:1.83.0
2026-01-29 16:43:46 DBG running cli command [hauler store add image]
2026-01-29 16:43:46 DBG using store at [/home/user/store]
2026-01-29 16:43:46 INF adding image [x.x.x.x:8082/track-line-diagram:1.83.0] to the store
2026-01-29 16:43:47 DBG multi-arch image [false]
2026-01-29 16:43:53 INF rewriting [x.x.x.x:8082/track-line-diagram:1.83.0] to [index.docker.io/nexus/track-line-diagram:1.83.0]
2026-01-29 16:43:53 INF successfully added image [x.x.x.x:8082/track-line-diagram:1.83.0]
$ hauler store info
+-------------------------------------------------+-------+-------------+----------+---------+
| REFERENCE                                       | TYPE  | PLATFORM    | # LAYERS | SIZE    |
+-------------------------------------------------+-------+-------------+----------+---------+
| helm/track-line-diagram:1.83.0                  | chart | -           |        1 | 2.9 MB  |
| index.docker.io/nexus/track-line-diagram:1.83.0 | image | linux/amd64 |       11 | 8.5 MB  |
+-------------------------------------------------+-------+-------------+----------+---------+
|                                                                          TOTAL   | 11.4 MB |
+-------------------------------------------------+-------+-------------+----------+---------+

Here..

• add a chart - ok
• add an image - chart gone. image ok
• add chart with rewrite - image gone, chart with rename ok
• add image with rename - renamed chart and renamed image ok

the same effect is seen with hauler add chart --add-images where the refernces images name is as above.

if you need a better example.. let me know what is needed.