Common GN Dependency Errors

Use this reference to classify Chromium GN dependency failures before editing.

Include not allowed by DEPS

The include is blocked by a DEPS file, not merely by a missing BUILD.gn dependency.

Typical causes:

• The directory's DEPS rules intentionally forbid this layer from including the target header.
• The include path needs a narrow specific_include_rules exception.
• The code should depend on a lower-level abstraction instead of the forbidden header.

Safe response:

1. Read the nearest relevant DEPS file and any parent DEPS files.
2. Check whether similar files in the same directory already have an allow rule.
3. Prefer changing the code to follow the intended layering.
4. Add an allow rule only when it matches existing architecture and is as narrow as possible.

Can't include this header from here

GN can see the header, but the current target is not allowed to include it through the declared dependency path. This often means the dependency is private to another target or only reachable transitively.

Safe response:

1. Find the owner target of the including file.
2. Find the owner target of the included header.
3. Add a direct dependency to the including target when the dependency direction is valid.
4. If the include is in a public header, decide whether the owner target needs public_deps or whether the include can move to the .cc file.

Missing direct dependency

The build succeeds only because another target brings in the header transitively, or it fails because direct dependency checking is enabled.

Safe response:

• Add the direct dependency to the target that owns the source file.
• Keep it in deps unless a public header exposes the dependency.

Private header visibility

The header belongs to an implementation target that is not meant to be consumed directly.

Safe response:

• Look for a public/interface target in the same directory.
• Include the public API header instead of a private implementation header.
• If no public API exists, consider whether the dependency direction is wrong.

Circular dependency

Adding the obvious dependency creates a GN cycle.

Safe response:

• Do not add broader aggregate deps to hide the cycle.
• Split public headers from implementation if that reduces the cycle.
• Move shared interfaces to a lower-level target.
• Use forward declarations in headers when possible.
• Consider dependency injection instead of direct concrete-type dependencies.