nodejs/node · error · GypError

Dependency '%s' not found

Error message

Dependency '%s' not found

What it means

In VerifyNoGYPFileCircularDependencies, gyp builds a graph at the .gyp-FILE level (not target level). For each dependency it computes the build file; if that file differs from the current file and is not already a node, it raises GypError 'Dependency not found'. This means a .gyp file references another build file that gyp never loaded as a node.

Source

Thrown at tools/gyp/pylib/gyp/input.py:2009

    for target, spec in targets.items():
        build_file = gyp.common.BuildFile(target)
        build_file_node = dependency_nodes[build_file]
        target_dependencies = spec.get("dependencies", [])
        for dependency in target_dependencies:
            try:
                dependency_build_file = gyp.common.BuildFile(dependency)
            except GypError as e:
                gyp.common.ExceptionAppend(
                    e, "while computing dependencies of .gyp file %s" % build_file
                )
                raise

            if dependency_build_file == build_file:
                # A .gyp file is allowed to refer back to itself.
                continue
            dependency_node = dependency_nodes.get(dependency_build_file)
            if not dependency_node:
                raise GypError("Dependency '%s' not found" % dependency_build_file)
            if dependency_node not in build_file_node.dependencies:
                build_file_node.dependencies.append(dependency_node)
                dependency_node.dependents.append(build_file_node)

    # Files that have no dependencies are treated as dependent on root_node.
    root_node = DependencyGraphNode(None)
    for build_file_node in dependency_nodes.values():
        if len(build_file_node.dependencies) == 0:
            build_file_node.dependencies.append(root_node)
            root_node.dependents.append(build_file_node)

    flat_list = root_node.FlattenToList()

    # If there's anything left unvisited, there must be a circular dependency
    # (cycle).
    if len(flat_list) != len(dependency_nodes):
        if not root_node.dependents:
            # If all files have dependencies, add the first file as a dependent

View on GitHub (pinned to 1b2de5e052)

Solutions

  1. Confirm the referenced .gyp file path is correct and the file exists.
  2. Make sure the .gyp file is actually included by the top-level build file (transitively).
  3. Check relative-path resolution and OS path separators.
  4. Ensure the target's declaring file is not hidden behind a false conditional.

Example fix

// before: 'dependencies': ['missing.gyp:x']  // missing.gyp never loaded
// after: add 'missing.gyp' to includes, or fix path to '../sub/missing.gyp:x'
Defensive patterns

Strategy: validation

Validate before calling

import gyp.common, os
loaded_files = set(os.path.abspath(f) for f in build_files)
for t, spec in targets.items():
    bf = gyp.common.BuildFile(t)
    for d in spec.get('dependencies', []):
        dbf = gyp.common.BuildFile(d)
        if dbf != bf and os.path.abspath(dbf) not in loaded_files:
            raise SystemExit('Referenced build file not loaded: %r' % dbf)

Try / catch

try:
    gyp.main(args)
except gyp.input.GypError as e:
    if "Dependency '" in str(e) and 'not found' in str(e): print('Check .gyp file inclusion/paths'); raise

Prevention

When it happens

Trigger: A .gyp file's dependency list names a qualified target whose build-file component (gyp.common.BuildFile(dependency)) yields a build file with no corresponding node in dependency_nodes. Reached during the file-level graph build before the cycle check.

Common situations: A dependency points at a .gyp file that was not included/loaded (wrong relative path, missing include, file deleted); path normalization differences; referencing a target in a file only loaded under a disabled conditional.

Related errors

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/eb937c1d803be9a5. Report an issue: GitHub.