bazelbuild/bazel · error · OptionProcessorException

Unable to find the type of annotation %s.

Error message

Unable to find the type of annotation %s.

What it means

ProcessorUtils.getAnnotation throws this when the annotation processor cannot resolve the TypeElement for a requested annotation class — classpath visibility is broken. Concretely, the comment in the source notes this happens when the annotation type is on the processor's -processorpath but not on the compile -classpath, so the compiler's element utilities return null for it.

Source

Thrown at src/main/java/com/google/devtools/common/options/processor/ProcessorUtils.java:41

import javax.lang.model.type.DeclaredType;
import javax.lang.model.type.TypeMirror;
import javax.lang.model.util.Elements;
import javax.lang.model.util.Types;

/** Convenient utilities for dealing with the javax.lang.model types. */
public class ProcessorUtils {

  /** Return the AnnotationMirror for the annotation of the given type on the element provided. */
  static AnnotationMirror getAnnotation(
      Elements elementUtils,
      Types typeUtils,
      Element element,
      Class<? extends Annotation> annotation)
      throws OptionProcessorException {
    TypeElement annotationElement = elementUtils.getTypeElement(annotation.getCanonicalName());
    if (annotationElement == null) {
      // This can happen if the annotation is on the -processorpath but not on the -classpath.
      throw new OptionProcessorException(
          element, "Unable to find the type of annotation %s.", annotation);
    }
    TypeMirror annotationMirror = annotationElement.asType();

    for (AnnotationMirror annot : element.getAnnotationMirrors()) {
      if (typeUtils.isSameType(annot.getAnnotationType(), annotationMirror)) {
        return annot;
      }
    }
    // No annotation of this requested type found.
    throw new OptionProcessorException(
        element, "No annotation %s found for this element.", annotation);
  }

  /**
   * Returns the contents of a {@code Class}-typed field in an annotation.
   *
   * <p>Taken & adapted from AutoValueProcessor.java

View on GitHub (pinned to e6e199d060)

Solutions

1. Ensure the JAR containing the annotation (e.g. com.google.devtools.common.options.Option) is on the compile classpath of the module being compiled, not only on -processorpath.
2. Prefer building via Bazel (bazel build //src:bazel-dev and dependent targets) so processor/classpath deps are wired consistently rather than hand-rolled javac flags.
3. Check for version skew: the annotation seen by the processor and by javac must come from the same library version.
4. In IDEs, re-import/refresh the Bazel project so annotation processor paths regenerate.

Example fix

// before: custom javac with annotation only on processor path
javac -processorpath lib/options-processor.jar \
      -classpath app.jar \
      src/MyOptions.java   // Option class not on -classpath -> error
// after: put the annotations jar on the compile classpath too
javac -processorpath lib/options-processor.jar \
      -classpath app.jar:lib/options-annotations.jar \
      src/MyOptions.java

// Build-time sanity: verify the annotation class is resolvable on the compile classpath
static boolean annotationOnCompileClasspath(ClassLoader compileCpLoader,
                                             String annotationFqn) {
  try {
    Class.forName(annotationFqn, false, compileCpLoader);
    return true;
  } catch (ClassNotFoundException e) {
    return false;
  }
}

When it happens

Trigger: Compiling options classes where com.google.devtools.common.options.Option (or another annotation the processor inspects) is resolved by the processor but absent from the compilation classpath — mismatched -processorpath/-classpath, an annotation JAR shaded differently between the two, or a broken toolchain/IDE annotation-processing classpath setup.

Common situations: Building with a custom javac invocation that puts options libraries only on -processorpath; IDE (IntelliJ/Eclipse) annotation-processing configuration diverging from Bazel's; upgrading the options library so processor and annotation come from different versions; migrating a build to Bazel with half-configured javac_opts.

Related errors

• Option includes UNKNOWN with other, known, effects. Please r
• Option includes NO_OP with other effects. This doesn't make
• Option has metadata tag %s but does not have category UNDOCU
• Documentation level is no longer read from the option catego
• Can't set an option to be both an expansion option and have

AI-assisted analysis of bazelbuild/bazel@e6e199d060 (2026-08-14). Data as JSON: /api/errors/0027783899c222c7. Report an issue: GitHub.