1.1.10 Common Error Messages

Most Bazel errors look longer than they are. Start with the first specific ERROR: line instead of the final "build aborted" summary. It usually names what Bazel could not resolve, evaluate, compile, or run, which tells you where to look first. You rarely need to understand every line at once.

Which Bazel layer should you inspect first?

Find the first distinctive error phrase, then inspect the Bazel layer it names.

Match the phrase to the first check

NO SUCH TARGET

label or target

Check the requested or referenced label

Then check the target definition

deps = ["//lib:missing"]

NO SUCH PACKAGE

package path

Check the package path and BUILD file

For an external repo, check repo resolution

pkg/BUILD.bazel · MODULE.bazel

VISIBILITY ERROR

access rule

Check the dependency's visibility

Target exists, but access is denied

visibility / package_group()

TRACEBACK

Starlark call stack

Follow the BUILD call into .bzl

Starlark evaluation failed

BUILD.bazel -> defs.bzl

NO MATCHING TOOLCHAINS

toolchain selection

Check platform and toolchain registration

No compatible toolchain

--platforms / register_toolchains()

Error families point to different first checks: missing label or package, blocked visibility edge, Starlark evaluation, or toolchain selection.

Start With The First Specific Error

You do not need to recognize Bazel's loading, analysis, and execution phases yet. Match the message you see to one of these shapes:

no such target - the package loaded, but the referenced target name is wrong.
no such package - Bazel could not resolve the package or external repository.
syntax error in BUILD.bazel - Bazel could not evaluate the package.
Visibility error - the dependency exists, but the producer does not allow it.
Compiler "package/symbol/header not found" output - source code used a dependency the target did not declare.
Traceback - a BUILD or .bzl file failed during Starlark evaluation.
No matching toolchains found - Bazel could not select a required tool.¹^,²
Target ... is incompatible - the target exists, but rejects the active platform.
A missing runfile or environment value - analysis succeeded, but execution used runtime state the target did not declare.

That match is enough to choose a first response. The sections below show what to inspect for each shape. 2.2.2 Reading Build Output later gives precise names to the phases behind them.

`no such target` Means "Wrong Name In A Package That Exists"

This is the friendlier of the two label-resolution failures. Bazel has already found the package. The problem is narrower: the target name inside that package does not exist.

Won't build

alias(
    name = "broken",
    actual = "//lib:missing",
)

ERROR: .../lib/BUILD.bazel: no such target '//lib:missing': target 'missing' not declared in package 'lib' ...
ERROR: .../BUILD.bazel:1:6: no such target '//lib:missing' ... and referenced by '//:broken'
ERROR: Analysis of target '//:broken' failed; build aborted: Analysis failed

Reproduce this error

The error points to the consuming location where the bad label was referenced, not to the place where the missing target "should have been"³. When a refactor renames :api_proto_java_lib to something else, the fix is usually in a dependent package that still uses the old label³.

So the first response is mechanical:

open the referenced BUILD file,
compare the label against the actual name = declarations in the target package,
if the package was recently reorganized, re-check the full label syntax from 0.2.1 Label Anatomy instead of guessing from memory.

`no such package` Means The Package Was Never Resolved

no such package is broader: the package itself could not be loaded, or an external repository behind the label never resolved in the first place.

One local version is a label that points at a directory with no BUILD file:

Won't build

alias(
    name = "broken_local_package",
    actual = "//missing:dep",
)

ERROR: no such package 'missing': BUILD file not found in any of the following directories. Add a BUILD file to a directory to mark it as a package.
 - missing
ERROR: .../BUILD.bazel:1:6: no such package 'missing': BUILD file not found in any of the following directories. Add a BUILD file to a directory to mark it as a package.
 - missing and referenced by '//:broken_local_package'
ERROR: Analysis of target '//:broken_local_package' failed; build aborted: Analysis failed

The external-repository version has the same shape, but the unresolved package starts with @:

ERROR: no such package '@@[unknown repo 'not_declared' requested from @@]//': The repository '@@[unknown repo 'not_declared' requested from @@]' could not be resolved: No repository visible as '@not_declared' from main repository
ERROR: .../BUILD.bazel:6:6: no such package '@@[unknown repo 'not_declared' requested from @@]//': The repository '@@[unknown repo 'not_declared' requested from @@]' could not be resolved: No repository visible as '@not_declared' from main repository and referenced by '//:broken_external_repo'
ERROR: Analysis of target '//:broken_external_repo' failed; build aborted: Analysis failed

Reproduce this error

This commonly appears when generated BUILD files reference external repositories that have not been configured yet⁴. The label syntax may be fine while the repository behind @repo is missing.

That changes the first response:

if the label starts with @, inspect MODULE.bazel or legacy WORKSPACE before touching source code,
if the repository should already exist, use 1.1.11 bazel fetch or other dependency-inspection commands to separate fetch/setup failures from normal build failures,
if the label is local rather than external, re-check whether the directory is a Bazel package from 0.1.3 Package.

`syntax error` Means The Package Did Not Load

Sometimes Bazel has found the package directory, but the BUILD.bazel file is not valid Starlark. In this example, the closing ] is missing from srcs, so no target declarations in that package are reliable yet.

Won't build

filegroup(
    name = "demo",
    srcs = ["message.txt",
)

ERROR: .../broken/BUILD.bazel:4:1: syntax error at ')': expected ]
WARNING: Target pattern parsing failed.
ERROR: Skipping '//broken:demo': no such target '//broken:demo': target 'demo' not declared in package 'broken' ...
ERROR: no such target '//broken:demo': target 'demo' not declared in package 'broken' ...

The first line is the one to fix. The later no such target lines are fallout: because loading stopped at the syntax error, Bazel never created :demo in the package. Fix the BUILD.bazel syntax before chasing labels or dependencies.

Reproduce this error

Visibility Errors Mean The Edge Exists, But Access Is Denied

A visibility failure is not a spelling problem. Bazel resolved both ends of the dependency edge and then rejected the edge during analysis because the producer target did not grant access⁵.

Won't build

java_binary(
    name = "server",
    srcs = ["Main.java"],
    main_class = "app.Main",
    deps = ["//lib:internal"],
)

ERROR: .../app/BUILD.bazel:3:12: in java_binary rule //app:server: Visibility error:
target '//lib:internal' is not visible from
target '//app:server'
Recommendation: modify the visibility declaration if you think the dependency is legitimate.

Reproduce this error

The rule behind it is simple: visibility controls who may depend on a target, and violations fail during analysis rather than compilation⁵. A practical consequence is that the fix usually belongs on the producer side, not the consumer side: visibility, default_visibility, package_group, or, for raw file targets, exports_files()⁵^,⁴.

When you see this family of error, go back to 0.2.4 Visibility and check:

is the producer intentionally private?
should the producer expose __pkg__ or __subpackages__ instead?
are you depending on a raw file that should have been exported or wrapped in a rule target?⁵^,⁴

Raw source files use the same visibility model. If another package reaches for //data:private.txt and that file was exported only privately, Bazel points at the consumer edge and tells you to fix the source-file target with exports_files():

Won't build

genrule(
    name = "copy_private",
    srcs = ["//data:private.txt"],
    outs = ["private_copy.txt"],
    cmd = "cp $(location //data:private.txt) $@",
)

ERROR: .../app/BUILD.bazel:1:8: in genrule rule //app:copy_private: Visibility error:
target '//data:private.txt' is not visible from
target '//app:copy_private'
Recommendation: modify the visibility declaration if you think the dependency is legitimate. ... To set the visibility of that source file target, use the exports_files() function

Reproduce this error

Missing Direct Dependencies Surface In The Compiler's Language

Not every missing dependency is a Bazel label error. Sometimes Bazel resolves the target correctly, but the compiler finds that its source imports code not listed in deps.

Won't build

java_binary(
    name = "server_missing_dep",
    srcs = ["Main.java"],
    main_class = "app.Main",
)

app/Main.java:3: error: package lib does not exist
import lib.Helper;
          ^
app/Main.java:7: error: cannot find symbol
    System.out.println(Helper.message());
                       ^
  symbol:   variable Helper
  location: class Main

The clue is that the message names a source import or symbol, not a missing Bazel package. Add the direct dependency to the consuming target instead of changing the Java import path:

java_binary(
    name = "server_fixed",
    srcs = ["Main.java"],
    main_class = "app.Main",
    deps = ["//lib:helper"],
)

Reproduce this error

0.3.3 Attributes & Semantic Roles explains the role of deps. Use 2.1.4 Common Dependency Issues when the dependency graph needs deeper diagnosis.

A Starlark Traceback Means BUILD Evaluation Failed

If the message starts with Traceback, read it like Python: the top frame shows the BUILD call site, and the deeper frames show the macro or helper code that failed.

Won't build

broken_macro(name = "demo")

ERROR: Traceback (most recent call last):
    File ".../BUILD.bazel", line 3, column 13, in <toplevel>
        broken_macro(name = "demo")
    File ".../defs.bzl", line 3, column 13, in broken_macro
        greeting.upperr()
Error: 'string' value has no field or method 'upperr' (did you mean 'upper'?)

Reproduce this error

The same traceback pattern explains why a macro failed while evaluating a BUILD file⁶. Do not skim straight to the final "package contains errors" line. Follow the stack from the BUILD call into the .bzl function that failed.

This family usually means one of three things:

plain syntax mistake in BUILD or .bzl,
invalid operation during Starlark evaluation,
macro/helper logic that assumed a value shape Bazel did not provide.⁶

`No matching toolchains found` Is A Configuration Problem

This message looks intimidating because it appears late in analysis, but the first response is straightforward: Bazel needed a mandatory toolchain type and could not resolve any registered implementation for the active platform setup².

Won't build

demo_rule(
    name = "demo",
)

ERROR: .../BUILD.bazel:3:10: While resolving toolchains for target //:demo (...): No matching toolchains found for types:
  //toolchain:demo_toolchain_type
To debug, rerun with --toolchain_resolution_debug='//toolchain:demo_toolchain_type'

Reproduce this error

Unresolved mandatory toolchains stop analysis. First check toolchain registration (register_toolchains() or --extra_toolchains) plus the target and execution platform constraints that guide resolution². 3.3 Configurable Builds & Platform Basics and 4.6 Toolchains & Platform Resolution explain the full resolution model.

Start with these checks:

confirm whether you passed --platforms or another config that changed platform selection,
check whether the relevant ruleset registered the toolchain it expects,
rerun with the suggested --toolchain_resolution_debug=... flag before guessing.

Incompatible Targets Are Platform Rejections

An incompatible target is different from a missing target. Bazel found the target, checked its compatibility metadata, and rejected the explicit request for the selected platform:

Won't build

bazel build --platforms=//platforms:linux //app:mac_only

ERROR: Analysis of target '//app:mac_only' failed; build aborted: Target //app:mac_only is incompatible and cannot be built, but was explicitly requested.
Dependency chain:
    //app:mac_only (...)   <-- target platform (//platforms:linux) didn't satisfy constraint //platforms:demo_macos

First inspect target_compatible_with, the selected --platforms value, and whether the target was requested explicitly or through a wildcard. Wildcards such as //... normally skip incompatible targets. An explicit request fails unless you opt into skipping it.

Reproduce this error

3.3.4 Target Compatibility explains the full compatibility behavior.

Runtime And Action-Environment Errors Happen During Execution

These errors appear after Bazel has successfully analyzed the target. The command or launched binary then tries to use runtime state it did not declare.

For a missing runfile, the broken target may look like this:

Won't build

sh_binary(
    name = "broken_reader",
    srcs = ["read_message.sh"],
    args = ["_main/app/message.txt"],
    deps = ["@bazel_tools//tools/bash/runfiles"],
)

missing runfile: _main/app/message.txt
declare it in data and pass it with $(rlocationpath ...)

Files needed after the binary starts belong in data. Pass a portable $(rlocationpath ...) value instead of guessing the runfiles path.

Reproduce this error

1.1.2 bazel run & Runfiles walks through the corrected runtime setup.

An action can fail in a similar way when it assumes that a host environment variable will be present:

Won't build

genrule(
    name = "needs_env",
    outs = ["token.txt"],
    cmd = "test \"$${DEMO_TOKEN:-}\" = expected || exit 1",
)

missing DEMO_TOKEN in action environment
fix: bazel build --action_env=DEMO_TOKEN=expected //env:needs_env

Do not rely on every developer having the same shell environment. Remove the host dependency when possible, or pass the intended value explicitly with --action_env=NAME=value.

Reproduce this error

For repository-wide environment policy and the hermeticity trade-offs, continue with 3.2.6 Hermeticity Settings and 2.3 Hermeticity & Sandboxing.

Reproducible Error Snippet Index

Use these tiny workspaces when you want to compare an error in your repository against a controlled version:

Error family	Snippet	First file to inspect
Wrong target in an existing package	no-such-target-error	`BUILD.bazel`
Package or external repo cannot be resolved	no-such-package-error	`BUILD.bazel`, then `MODULE.bazel`
BUILD file cannot be loaded	build-syntax-error	syntax near the first `ERROR:` line
Visibility policy rejects an edge	visibility-error	producer `visibility`, `package_group`, or `exports_files()`
Raw file visibility rejects an edge	exports-files-error	source file `exports_files()` visibility
Source imports code without a direct dep	missing-dependency-error	consumer target `deps`
Production target depends on test-only code	testonly-error	consumer target and helper package policy
Starlark evaluation fails	starlark-traceback-error	top stack frame, then failing `.bzl` helper
No platform branch/default matches	select-errors	`select()` keys and active `--platforms`
Required toolchain is not registered	toolchain-resolution-error	toolchain registration and platform constraints
Explicit target is incompatible with the active platform	target-compatibility	`target_compatible_with` and `--platforms`
Genrule path or tool declaration is wrong	genrule-sandbox-paths	`srcs`, `tools`, `outs`, and Make variables
Runtime file is missing from runfiles	missing-runfiles-error	`data` and `$(rlocationpath ...)`
Action assumes an undeclared env var	action-env-error	`--action_env` or removing the host dependency

key takeaway

Begin with the first specific error. Later messages may only describe its fallout. Ask how far Bazel got: resolution and loading point to labels, packages, or Starlark. Analysis points to dependency, toolchain, or platform configuration. Compiler output points to source imports and direct deps. execution failures point to undeclared runtime files or environment. Then use the smallest matching reproduction to test that classification before changing unrelated configuration.

Check your understanding · 2 questions

1.Match each error headline to the first place to inspect:

Drag each answer onto the matching prompt, or click an answer and then click a prompt

Answers

no such target

no such package

Visibility error

Traceback

No matching toolchains found

2.True or false: first-response error triage.

Choose True or False for each sentence

A syntax error can cause later no-such-target messages as fallout.

A visibility failure means the target name could not be resolved.

A toolchain-resolution failure should be diagnosed by deleting bazel-out first.

0 of 2 answered

Toolchains — unresolved mandatory toolchains halt analysis, registration via register_toolchains() / --extra_toolchains, and --toolchain_resolution_debug ↩
Toolchains — operator-facing explanation of mandatory toolchain resolution failures and first debugging steps ↩¹ ↩² ↩³
BazelCon 2019 Day 2: Half-Day Bazel Bootcamp (Part 2) — no such target after a rename points to the consuming BUILD file that still references the old label ↩¹ ↩²
Building a Go project using Bazel — unresolved external repositories causing no such package, plus a concrete visibility failure fixed with exports_files() ↩¹ ↩² ↩³
Visibility — target visibility is enforced during analysis, and the fix lives in the producer target's visibility policy ↩¹ ↩² ↩³ ↩⁴
Configurable Build Attributes — real BUILD-to-.bzl traceback showing how Starlark evaluation failures surface in Bazel ↩¹ ↩²

← PreviousExit Codes Next →bazel fetch

1.1.10 Common Error Messages

Start With The First Specific Error

no such target Means "Wrong Name In A Package That Exists"

no such package Means The Package Was Never Resolved

syntax error Means The Package Did Not Load

Visibility Errors Mean The Edge Exists, But Access Is Denied

Missing Direct Dependencies Surface In The Compiler's Language

A Starlark Traceback Means BUILD Evaluation Failed

No matching toolchains found Is A Configuration Problem

Incompatible Targets Are Platform Rejections

Runtime And Action-Environment Errors Happen During Execution

Reproducible Error Snippet Index

Footnotes

`no such target` Means "Wrong Name In A Package That Exists"

`no such package` Means The Package Was Never Resolved

`syntax error` Means The Package Did Not Load

`No matching toolchains found` Is A Configuration Problem