`go_deps` materializes a main repo module as a redundant `go_repository` when another module imports it

[rdesgroppes]

What version of gazelle are you using?

0.52.2

What version of rules_go are you using?

0.61.1

What version of Bazel are you using?

9.2.0

Does this issue reproduce with the latest releases of all the above?

Yes. I built a minimal repro against current bazel-contrib/bazel-gazelle master with a real bazel build, not just by reading the code, and it reproduces there too.

What operating system and processor architecture are you using?

Linux x86_64, but this is not OS- or architecture-specific: it is a pure label-resolution issue in the go_deps Bzlmod extension.

What did you do?

We have a monorepo (github.com/DataDog/datadog-agent) that:

• declares a single Bazel module at the repo root,
• uses go_deps.from_file(go_work = "//:go.work"), where go.work lists dozens of use () entries, each its own Go module with its own go.mod,
• has checked-in BUILD.bazel files for every one of those in-tree modules, reachable at //<path>, produced by our own root //:gazelle invocation with a gazelle:prefix directive matching the repo's module path,
• has these go.work members replace-ing each other locally in their own go.mod files on top of go.work. For example, one member's go.mod has a replace directive pointing another member's import path at a relative local path, and that member is in turn replaced the same way by several sibling modules' go.mod files.

Separately, an external Go module is consumed via the same go_deps extension and imports one of those same in-tree packages by its fully-qualified import path.

I built a minimal, real, bazel build-verified repro of this (not just a code reading) with the following shape:

repo/
├── MODULE.bazel          # bazel_dep(gazelle), go_deps.from_file(go_work = "//:go.work")
├── go.work                # use ( . ./pkg/foo )
├── go.mod                  # module example.com/repo
│                            # require example.com/repo/pkg/foo v0.0.0-fake // indirect
│                            # require example.com/thirdparty v0.0.0-fake
│                            # replace example.com/repo/pkg/foo => ./pkg/foo
└── pkg/foo/
    ├── BUILD.bazel          # go_library(name = "foo", importpath = "example.com/repo/pkg/foo", ...), checked in
    ├── foo.go
    └── go.mod               # module example.com/repo/pkg/foo

Plus a thirdparty Go module (injected hermetically via go_deps.archive_override so the repro needs no network access) whose go.mod requires example.com/repo/pkg/foo and which imports it. A go_binary at the repo root depends on both //pkg/foo and, transitively, on thirdparty.

The crucial, easy-to-miss ingredient is the replace example.com/repo/pkg/foo => ./pkg/foo line in the root's own go.mod. Without it, go_deps correctly avoids creating a duplicate repo for example.com/repo/pkg/foo. I verified this empirically too: removing that line makes the build fail differently, with an unrelated dangling-repository error rather than a duplicate-package one (see "Related, but distinct" below). With it, bazel build //... fails with:

package conflict error: example.com/repo/pkg/foo: multiple copies of package passed to linker:
    @@gazelle++go_deps+com_example_repo_pkg_foo//
    @@//pkg/foo

I traced why in internal/bzlmod/go_deps.bzl:

• go_deps walks every module_tag derived from parsing all of the workspace's go.mod files (via deps_from_go_mod) to compute MVS resolutions. For each module_tag.path, if module_tag.path in replace_map (replace_map is the union of every replace directive found in any go.work member's go.mod, collected earlier), the resulting module_resolutions[path] struct is given local_path = replacement.local_path, but no module_name attribute.
• The "unify" loop meant to make root-owned go.work members resolve to themselves instead of being fetched looks like this:

  for path, bazel_go_module in bazel_go_modules.items():
      if path in archive_overrides or path in gazelle_overrides or path in module_overrides or path in replace_map:
          continue
      if path in modules_from_go_work:
          module_resolutions[path] = bazel_go_module
          continue

  The override/replace check fires before the modules_from_go_work branch below it. So if the path is also a replace_map target (as pkg/foo is here, from some other go.work member's go.mod), the loop continues without ever overwriting module_resolutions[path] with the root-owned struct. The struct from the MVS pass, carrying local_path and no module_name, survives untouched.
• At repo creation time, if hasattr(module, "module_name"): continue is the only thing that skips declaring a go_repository for a root-owned path. Because the surviving struct has no module_name, this check does not fire, and go_deps calls go_repository(local_path = "pkg/foo", importpath = "example.com/repo/pkg/foo", ...), a second, independent go_library for source that's already tracked in-tree.

Any go_binary/go_test depending on both label spaces then fails at link time exactly as shown above.

What did you expect to see?

Since example.com/repo/pkg/foo (or, in our real case, the equivalent in-tree package) is a go.work member with its own in-tree, already-BUILD.bazel'd package, I expected go_deps to never create a second go_repository for it, regardless of whether some other go.work member's go.mod also happens to replace it. Concretely, the path in replace_map short-circuit in the unify loop should not bypass the path in modules_from_go_work unification when the path in question is a root-owned go.work member. Root ownership should take priority.

What did you see instead?

go_deps creates a second, independent go_repository (via local_path) for a go.work member whenever (a) some other module imports it and (b) any go.mod in the workspace has a replace directive targeting that same import path. In a monorepo where submodules commonly replace each other locally (as ours does, and as I'd expect most non-trivial go.work-based monorepos to, since it is the standard way to make a multi-module repo buildable both with and without go.work), this can affect any workspace member that another module happens to import. The result is two distinct Bazel labels providing the exact same Go import path from the exact same source files, and rules_go's linker correctly rejects the resulting duplicate with "multiple copies of package passed to linker."

Today we work around this in datadog-agent by hand-maintaining gazelle:resolve and gazelle:resolve_regexp directives in go_deps.gazelle_default_attributes(directives = [...]) that redirect every such import back to the in-tree label. This works, but:

• it has to be updated by hand every time a new external module starts importing one of our in-tree submodules,
• it silently stops working (falls back to the duplicate-label failure) if anyone forgets to update it,
• it does not address the case where two of our own go.work members cross-reference each other through the same external label space.

Related, but distinct, findings from building this repro (separate bugs, not covered by the analysis above, but worth mentioning since a real fix will likely touch the same code):

• Without the replace line above (no replace_map entry for the colliding path), the same setup fails differently. The colliding path is silently omitted from the shared bazel_gazelle_go_repository_config (filtered by if not getattr(module, "go_mod_dir", None)), so thirdparty's own Gazelle-generated BUILD.bazel ends up depending on a Bazel repo name that was never declared, and the build fails at analysis time with no such package '@@[unknown repo ...]'.
• A single-go.mod root module (no go.work at all) whose own top-level import path is required by another go_deps-materialized module hits yet another variant: the path is kept in bazel_gazelle_go_repository_config, but under the bogus repo name "@" + module.name, which is not the module's actual canonical repo name (@@, i.e. empty). The generated consumer BUILD.bazel then references a nonexistent @@<module_name> repo and fails with Repository '@@<module_name>' is not defined.

Related, but distinct, existing reports:

• Support for Bzlmod in a monorepo #1658 (general "multiple go.mod files in a Bzlmod monorepo" support question, unresolved since 2023),
• Gazelle Label Mismatch When Using go_deps Bzlmod Extension and default rules_go Repo Name #1958 (a different symptom of the same broad "labels generated by a go_deps-internal Gazelle invocation don't match what the root module expects" class of problem: repo_name mismatch rather than label duplication),
• Multiple copies of package passed to linker when using external tools #2084 (same linker symptom, different trigger: WORKSPACE/Bzlmod mixing for build tools),
• bazel mod tidy writes dangling use_repo entries for local go.work modules with replace #2336 / go_deps: don't declare use_repo dependency on module from go.work #2337 (a narrower, already-fixed bug: dangling use_repo entries for locally-replaced go.work members. That fix addressed bazel mod tidy bookkeeping, not repo generation, so it does not help here).

[jayconrod]

This sounds like a bug. go_deps should not generate a go_repository for any Go module provided by a Bazel module, including those covered by go.work. I've fixed a couple edge cases with this within Gazelle itself, but now I'm in the process of rewriting go_deps to better deal with go.work files as part of #2344. I'll try to fix this at the same time.

You mentioned you built a repro for this. Could you link to that? I think I can probably reproduce it from your description, but an actual repo would be much more helpful.

Kind of beside the point, but why use replace directives for other modules included in a go.work workspace? They shouldn't have any effect for the go tool, and seem to add complication for Bazel builds.

[jayconrod]

@rdesgroppes Reminder: please link a complete example that reproduces the issue. I think I can reproduce this, but I'd prefer to avoid making assumptions about what you're seeing.

I'm working on a new implementation of go_deps. I'm thinking about resolving this as follows:

1. When a go.mod or go.work file contains replace with a local path, we'll declare go_repository for it, copy the directory, and generate BUILD files. The source directory should not have BUILD files, though Gazelle may update any existing files.
2. When a go.work file contains use, we don't declare go_repository for it. The source directory should have BUILD files.
3. If a directory is referenced by both replace and use, it is an error, since we can't manage both patterns at the same time.

What you're describing would fall into case 3, so this would break entirely for you.

Could you say more about why both use and replace are used in your repo? If there's a strong need, maybe we can show a warning and ignore either use or replace when there's a conflict.

[rdesgroppes]

Reminder: please link a complete example that reproduces the issue. I think I can reproduce this, but I'd prefer to avoid making assumptions about what you're seeing.

@jayconrod Repro is up in the form of a draft PR against latest master, to envision where tests could fit: #2403, with 2 independent reproductions:

• tests/bcr/go_work_minimal, self-contained, reproduces the exact error text quoted above via cd tests/bcr/go_work_minimal && bazel build //...
• tests/bcr/go_work/consumer_check, inside the existing larger fixture, reproduces the same underlying duplicate-repository bug but surfaces a different visible error (a my_rules_go visibility gap) because that fixture aliases rules_go to a non-default repo name, via cd tests/bcr/go_work && bazel build //consumer_check/...

What you're describing would fall into case 3, so this would break entirely for you.

That's exactly our situation.

Could you say more about why both use and replace are used in your repo? If there's a strong need, maybe we can show a warning and ignore either use or replace when there's a conflict.

2 separate constraints, not an oversight.

We auto-generate replace directives across our ~150+ submodules to work around a go mod tidy/go list bootstrapping problem: those commands need the replace rules to succeed, but you need to run them successfully to discover which replace rules are missing in the first place. Nothing to do with go.work.

Separately, our CI and build tooling has for a long time run with go.work disabled, treating it as an IDE/gopls-only convenience rather than something the actual build depends on.
So historically, use and replace served 2 entirely separate consumers that never needed to be reconciled.

What's changed is that my team's mandate is bazelifying this repo's build, and Bazel/gazelle's go_deps is the first piece of tooling here that actually needs go.work to mean something, layered onto a parallel build system that still runs bits with go.work disabled and replace doing the real work.
So the overlap is a symptom of a build migration in progress, not a permanent architectural choice, but it's real, and I'd guess not unique to us: a design that hard-errors on use+replace together would presumably also break any other repo mid-migration to Bazel/gazelle from a replace-based build.
Once that migration is complete, we fully intend to clean up the legacy replace instrumentation, but we're not there yet.

Given that, would a warning plus a deterministic precedence (e.g. use wins when both apply, since the in-tree BUILD files already exist and are authoritative) be workable instead of a hard error?

Happy to test whatever direction you land on against both reproductions above.

[jayconrod]

Thanks for explaining. This is clear to me now.

And I appreciate the example PR too. The testing story for go_deps is not great, but I'm working on a unit testing system in #2397. When that's ready and go_deps is fixed, I'll incorporate those examples as test cases.

Given that, would a warning plus a deterministic precedence (e.g. use wins when both apply, since the in-tree BUILD files already exist and are authoritative) be workable instead of a hard error?

Yes, I think that's reasonable. There is a conflict here, but we don't want to make incremental migration impossible. We could make this a warning instead of an error and deterministically favor use.

My goal with the go_deps rewrite is to better support projects that use go.work files and have multiple Go modules within the same Bazel module, especially when packages in those modules need to be imported by Gazelle in other modules or by go_repository. This is a prerequisite for Gazelle v2, since we have a v2 submodule now. Should help with your situation too.

If you'll indulge my curiosity further, why 150+ submodules? Is that a step toward migrating to a monorepo, or do they need to be released independently? It sounds very difficult to manage.

[rdesgroppes]

If you'll indulge my curiosity further, why 150+ submodules?

Good question... will I see you at BazelCon 2026?

It sounds very difficult to manage.

Oh my, yes!

[jayconrod]

Good question... will I see you at BazelCon 2026?

Yes! Looking forward to hearing more.