Go replace Directive Errors - Fix Bad replace Paths in CI

A replace directive redirects a module to a local path or fork. When that target is missing on the CI runner - a sibling directory that was never checked out, or a folder without a go.mod - the build fails.

What this error means

A build fails with errors like replacement directory ../shared does not exist or replacement directory ../shared does not contain a go.mod file. It builds locally where the sibling repo exists, but not in CI where only one repo is checked out.

go: github.com/org/app/go.mod:
	replace github.com/org/shared => ../shared:
	replacement directory ../shared does not exist

Common causes

A local replace points outside the checked-out repo

A replace ... => ../sibling works on a developer machine where both repos are cloned side by side, but CI checks out only one, so the path is absent.

The replace target has no go.mod

A replacement directory must itself be a module. Pointing at a plain folder without a go.mod is rejected.

A leftover local replace committed by accident

A temporary local replace used for development was committed, breaking every environment that does not have that local path.

How to fix it

Check out the replacement repo in CI

When a local replace is intentional, clone the sibling module into the path the directive expects.

- uses: actions/checkout@v4
  with:
    repository: org/shared
    path: shared          # matches ../shared from the app dir

Replace with a published version instead

For a fork, redirect to a tagged module version rather than a local path so CI can fetch it.

// go.mod
replace github.com/org/shared => github.com/yourfork/shared v1.2.3

Remove an accidental local replace

go mod edit -dropreplace github.com/org/shared
go mod tidy

How to prevent it

• Avoid committing local-path replaces; use them only transiently.
• If a local replace is needed in CI, check out the target repo to the expected path.
• Prefer versioned fork replaces over local-directory ones.

Related guides