Import Cycles and Package Design

You are adding a login audit trail. The audit package stamps every action with the acting user, so it imports session for the user type:

// audit/audit.go
package audit

import "example.com/app/session"

func Record(actor session.User, action string) error {
	return store.Append(actor.ID, action)
}

The session package logs each new login through the same trail, so it imports audit:

// session/session.go
package session

import "example.com/app/audit"

func Login(u User) (Token, error) {
	if err := audit.Record(u, "login"); err != nil {
		return Token{}, err
	}
	return issue(u)
}

The build stops with the shortest, strictest error Go produces:

import cycle not allowed:
	session -> audit -> session

There is no flag to silence it and no configuration to relax it. Go forbids import cycles outright, and the reason is structural: package initialization order is derived from the import graph, and a cycle leaves the runtime no point where "finished initializing" is defined. The compiler refusing the cycle is the language refusing to invent an order that does not exist.

Notice where the cycle lives. It is not between files — two files in one package reference each other freely, no matter how tangled, because they compile as a unit. The cycle is between namespaces: session cannot see inside audit without importing it, audit cannot see inside session without importing it, and each package's exported surface now demands the other's existence. The package boundary you drew does not separate two responsibilities; it cuts through one collaboration and then demands they call each other.

That framing matters because the fix is never "find a way to keep the cycle." The fix is to remove an edge — by needing less, by moving shared vocabulary to common ground, or by inverting who knows whom. Three techniques, in the order you should reach for them.

Look again at what audit actually uses from session: actor.ID, a string. It imports an entire package — and its transitive closure — to read one field. The first question when facing a cycle is not "how do I rearrange these packages" but "which of these edges is pretending to be a need?"

// audit no longer imports session
package audit

func Record(actorID, action string) error {
	return store.Append(actorID, action)
}

// session builds the value audit needs
package session

import "example.com/app/audit"

func Login(u User) (Token, error) {
	if err := audit.Record(u.ID, "login"); err != nil {
		return Token{}, err
	}
	return issue(u)
}

The cycle is gone because one edge is gone, and nothing was sacrificed: audit never needed to construct or inspect a session.User. This fix has a name worth remembering — depend on what you use, not on what owns it. A parameter of type string instead of a foreign struct, a result returned as a plain value the caller already holds, a small interface with one method instead of a concrete package. Each substitution removes a package-level dependency and shrinks the API surface at the same time.

Reach for this first because it improves the design even when there is no cycle. A package that imports half the application to do its job is hard to test and harder to move; a package that takes strings and returns structs can be exercised with nothing but a go test file.

When the caller genuinely does not have the value — when audit must materialize a user-shaped thing on its own — the need is real, and the second technique applies: move the shared vocabulary to a package that sits below both.

// principal/principal.go — the leaf both sides can import
package principal

type User struct {
	ID    string
	Email string
}

Now session imports principal to create users, audit imports principal to read them, and neither imports the other. The dependency graph becomes a diamond instead of a loop: two packages over one shared leaf. The rule of thumb is that data types shared across a layer belong below the layer, in a package with no opinions about behavior — the same instinct that keeps internal boundaries honest and the same direction the compiler wants the arrows to point.

Some cycles are not about data at all. Suppose session needs a richer audit facility — retries, sampling, a failure policy — and the right implementation really does live in audit. Extracting types does not help because the dependency is behavioral: session needs to call audit.

Go's answer is to invert who knows whom, following the proverb: define interfaces where they are consumed.

// session declares what it needs — no import of audit
package session

type AuditTrail interface {
	Record(actorID, action string) error
}

type Sessioner struct {
	trail AuditTrail // supplied from outside
}

func (s *Sessioner) Login(u User) (Token, error) {
	if err := s.trail.Record(u.ID, "login"); err != nil {
		return Token{}, err
	}
	return issue(u)
}

// audit provides the implementation — imports session? No. It never names session.
package audit

func (t *Trail) Record(actorID, action string) error { /* ... */ }

// wiring happens at the top, where both packages are already legal to import
trail := &audit.Trail{}
s := &session.Sessioner{trail: trail}

The dependency arrows now point one way: audit knows nothing about session; session names only its own interface; main (or an app package) sees both and connects them. The cycle is not hidden — it is eliminated, because no package imports its own consumer.

The same shape shows up everywhere once you look: a handler declares the UserStore it needs and the repository satisfies it silently — implicit satisfaction means database/sql's driver interfaces work this way too (Interfaces and Implicit Satisfaction). Two side effects follow that people undervalue: session can be tested with a fake trail in five lines, and swapping implementations no longer touches the package that consumes them (Test Doubles with Interfaces).

One warning: do not invert reflexively. If both packages are already one package's business, merging them is simpler than an interface between them. An interface earns its place when you need the substitution or when it is the only edge left to cut — after needing less and sharing a leaf, it is the third tool, not the first.

Import cycles rarely arrive as isolated mistakes. They cluster around three smells, and recognizing the smell fixes the root cause instead of the symptom.

The packages are too small. If session and audit are three files each and half of each file exists to serve the other, the boundary is churn, not structure. Files within a package cannot cycle; merging them into one package — say login — makes the collaboration internal and invisible to the compiler's import graph. Splitting is for consumers outside the unit, not for every noun in the README. When you split, split along lines someone else crosses (When a Folder Becomes a Package).

Registration is hiding in init(). The classic shape: a registry package holds a map, plugins import it to register themselves, and the registry imports the plugins to instantiate them. Cycle. The wiring does not belong in package initialization — it belongs at the top:

// main assembles; packages stay unaware of each other
registry := NewRegistry()
registry.Register("sqlite", &sqlite.Driver{})
registry.Register("postgres", &postgres.Driver{})
app := NewApp(registry)

Each driver now registers through a value it was handed or simply gets passed into Register by whoever imports both. Initialization order stops being architecture.

The cycle repeats because only internal was tried. Visibility is orthogonal to cycles: internal controls who may import a package, and the two packages in your loop are still allowed to import each other — they sit in the same subtree. The error message does not change. Only removing an edge changes it: shrink the need, move the shared type down, invert the call, or merge the units. Any "solution" that keeps both arrows is decoration.

For review, a compact checklist: does the cycle carry data or behavior? Data → a smaller parameter or a shared leaf package. Behavior → a consumer-declared interface wired from above. Both → probably one package. After the fix, confirm the arrows point the same direction across the whole repo — a graph with no cycles and a consistent flow is what lets each package be compiled, tested, and understood alone. When that graph is a set of modules you build and version together, the tooling question changes shape entirely, which is where Multi-Module Workspaces with go.work takes over.