https://checkerframework.org
Version 4.3.1 (2026-10-08)
For the impatient: Section 1.3 describes how to install and use pluggable type-checkers.
This manual is also available as a single HTML page and in PDF.
1 Introduction
1.1 How to read this manual
1.2 How it works: Pluggable types
1.3 Installation
1.4 Example use: detecting a null pointer bug
2 Using a checker
2.1 Where to write type annotations
2.2 Running a checker
2.3 What the checker guarantees
2.4 Tips about writing annotations
3 Nullness Checker
3.1 What the Nullness Checker guarantees
3.2 Nullness annotations
3.3 Writing nullness annotations
3.4 Suppressing nullness warnings
3.5 Examples
3.6 Tips for getting started
3.7 Other tools for nullness checking
3.8 Initialization Checker
4 Map Key Checker
4.1 Invoking the Map Key Checker
4.2 Map key annotations
4.3 Default annotations
4.4 Examples
4.5 Local inference of @KeyFor annotations
5 Optional Checker for possibly-present data
5.1 How to run the Optional Checker
5.2 Optional annotations
5.3 What the Optional Checker guarantees
5.4 Suppressing optional warnings
6 Interning Checker
6.1 Interning annotations
6.2 Annotating your code with @Interned
@Interned
6.3 Interned classes
6.4 What the Interning Checker checks
6.5 Examples
6.6 Other interning annotations
7 Called Methods Checker for the builder pattern and more
7.1 How to run the Called Methods Checker
7.2 For Lombok users
7.3 Specifying your code
7.4 Default handling for Lombok and AutoValue
7.5 Using the Called Methods Checker for properties unrelated to builders
7.6 More information
8 Resource Leak Checker for must-call obligations
8.1 How to run the Resource Leak Checker
8.2 Resource Leak Checker annotations
8.3 Example of how safe resource usage is verified
8.4 Aliased references and ownership transfer
8.5 Resource aliasing
8.6 Creating obligations (how to re-assign a non-final owning field)
8.7 Ignored exception types
8.8 Errors about field initialization
8.9 Errors about unknown must-call obligations
8.10 Collections of resources
8.11 Further reading
9 Fake Enum Checker for fake enumerations
9.1 Fake enum annotations
9.2 What the Fenum Checker checks
9.3 Running the Fenum Checker
9.4 Suppressing warnings
9.5 Example
9.6 The fake enumeration pattern
9.7 References
10 Lock Checker
10.1 What the Lock Checker guarantees
10.2 Lock annotations
10.3 Type-checking rules
10.4 Examples
10.5 More locking details
10.6 Other lock annotations
10.7 Possible extensions
11 Index Checker for sequence bounds (arrays and strings)
11.1 Index Checker structure and annotations
11.2 Lower bounds
11.3 Upper bounds
11.4 Sequence minimum lengths
11.5 Sequences of the same length
11.6 Binary search indices
11.7 Substring indices
11.8 Inequalities
11.9 Annotating your own fixed-size datatypes
11.10 Technical papers
12 Tainting Checker
12.1 Tainting annotations
12.2 Tips on writing @Untainted annotations
@Untainted
12.3 @Tainted and @Untainted can be used for many purposes
@Tainted
12.4 A caution about polymorphism and side effects
13 SQL Quotes Checker
13.1 SQL Quotes annotations
13.2 What the SQL Quotes Checker checks
13.3 Library annotations
14 Regex Checker for regular expression syntax
14.1 Regex annotations
14.2 Annotating your code with @Regex
@Regex
15 Format String Checker
15.1 Formatting terminology
15.2 Format String Checker annotations
15.3 What the Format String Checker checks
15.4 Implicit qualifiers
15.5 @FormatMethod
15.6 Testing whether a format string is valid
16 Internationalization Format String Checker (I18n Format String Checker)
16.1 Internationalization Format String Checker annotations
16.2 Conversion categories
16.3 Subtyping rules for @I18nFormat
@I18nFormat
16.4 What the Internationalization Format String Checker checks
16.5 Resource files
16.6 Running the Internationalization Format Checker
16.7 Testing whether a string has an i18n format type
16.8 Examples of using the Internationalization Format Checker
17 Property File Checker
17.1 General Property File Checker
17.2 Internationalization Checker (I18n Checker)
17.3 Compiler Message Key Checker
18 Signature String Checker for string representations of types
18.1 Signature annotations
18.2 What the Signature Checker checks
19 GUI Effect Checker
19.1 GUI effect annotations
19.2 What the GUI Effect Checker checks
19.3 Running the GUI Effect Checker
19.4 Annotation defaults
19.5 Polymorphic effects
19.6 References
20 Units Checker
20.1 Units annotations
20.2 Extending the Units Checker
20.3 What the Units Checker checks
20.4 Running the Units Checker
20.5 Suppressing warnings
20.6 References
21 Signedness Checker
21.1 Annotations
21.2 Prohibited operations
21.3 Utility routines for manipulating unsigned values
21.4 Local type refinement
21.5 Instantiating polymorphism
21.6 Other signedness annotations
22 Modifiability Checker
22.1 Unmodifiable collections
22.2 Modifiability annotations
22.3 @Modifiable and @Unmodifiable for types without grow, seq-grow, shrink, and/or replace methods
@Modifiable
@Unmodifiable
22.4 Behavior of the iterator() method
iterator()
22.5 Examples of Modifiability Checker warnings
23 Purity Checker
23.1 Purity annotations
23.2 Purity annotations are trusted
23.3 Overriding methods inherit specifications from overridden methods
23.4 Suppressing warnings
24 Constant Value Checker
24.1 Annotations
24.2 Other constant value annotations
24.3 Warnings
24.4 Unsoundly ignoring overflow
24.5 Strings can be null in concatenations
25 Returns Receiver Checker
25.1 Annotations
25.2 AutoValue and Lombok support
26 Reflection resolution
26.1 Reflection resolution example
26.2 MethodVal and ClassVal Checkers
27 Initialized Fields Checker
27.1 Running the Initialized Fields Checker
27.2 Motivation: uninitialized fields
27.3 Example
27.4 Annotations
27.5 Comparison to the Initialization Checker
28 Aliasing Checker
28.1 Aliasing annotations
28.2 Leaking contexts
28.3 Restrictions on where @Unique may be written
@Unique
28.4 Aliasing type refinement
29 Must Call Checker
29.1 Must Call annotations
29.2 Writing @MustCall/@InheritableMustCall on a class
@MustCall
@InheritableMustCall
29.3 Relationship to lightweight ownership
29.4 Assumptions about reflection
29.5 Type parameter bounds often need to be annotated
30 Subtyping Checker
30.1 Using the Subtyping Checker
30.2 Subtyping Checker example
30.3 Type aliases and typedefs
31 Third-party checkers
31.1 Determinism checker
31.2 Constant Value Inference (Interval Inference)
31.3 Crypto Checker
31.4 AWS crypto policy compliance checker
31.5 AWS KMS compliance checker
31.6 PUnits units of measurement
31.7 JaTyC typestate checker
31.8 NullAway
31.9 Nullness Rawness Checker
31.10 UI Thread Checker for ReactiveX
31.11 Practical Immutability For Classes And Objects (PICO)
31.12 Read Checker and Cast Checker for ensuring that EOF is recognized
31.13 Ontology type system
31.14 Glacier: Class immutability
31.15 SQL checker that supports multiple dialects
31.16 Immutability checkers: IGJ, OIGJ, and Javari
31.17 JCrypt: computation over encrypted data
31.18 DroidInfer: information flow
31.19 Error Prone linter
31.20 SPARTA information flow type-checker for Android
31.21 SFlow type system for information flow
31.22 CheckLT taint checker
31.23 EnerJ checker
31.24 ReIm immutability
31.25 SFlow x ReIm for information flow and reference immutability
31.26 Generic Universe Types checker
31.27 Safety-Critical Java checker
31.28 Thread locality checker
31.29 Units and dimensions checker
31.30 Typestate checkers
32 Generics and polymorphism
32.1 Generics (parametric polymorphism or type polymorphism)
32.2 Qualifier polymorphism for methods
32.3 Class qualifier parameters
33 Advanced type system features
33.1 Invariant array types
33.2 Context-sensitive type inference for array constructors
33.3 Upper bound of qualifiers on uses of a given type (annotations on a class declaration)
33.4 The effective qualifier on a type (defaults and inference)
33.5 Default qualifier for unannotated types
33.6 Annotations on constructors
33.7 Type refinement (flow-sensitive type qualifier inference)
33.8 Writing Java expressions as annotation arguments
33.9 Field invariants
33.10 Unused fields
34 Suppressing warnings
34.1 @SuppressWarnings annotation
@SuppressWarnings
34.2 @AssumeAssertion string in an assert message
@AssumeAssertion
assert
34.3 -AsuppressWarnings command-line option
-AsuppressWarnings
34.4 -AskipUses and -AonlyUses command-line options
-AskipUses
-AonlyUses
34.5 -AskipDefs and -AonlyDefs command-line options
-AskipDefs
-AonlyDefs
34.6 -AskipFiles and -AonlyFiles command-line options
-AskipFiles
-AonlyFiles
34.7 -Alint command-line option
-Alint
34.8 Change the specification of a method
34.9 Don’t run the processor
34.10 Checker-specific mechanisms
35 Type inference
35.1 Type inference tools
35.2 Whole-program inference
35.3 Running whole-program inference on a single project, with buildfile editing
35.4 Running whole-program inference on a single project, without buildfile editing
35.5 Running whole-program inference on many projects
35.6 Whole-program inference that inserts annotations into source code
35.7 Inference results depend on uses in your program or test suite
35.8 How whole-program inference works
35.9 Type inference compared to other whole-program analyses
36 Annotating libraries
36.1 Tips for annotating a library
36.2 Creating an annotated library
36.3 Creating an annotated JDK
36.4 Compiling partially-annotated libraries
36.5 Using stub classes
36.6 Ajava files
36.7 Troubleshooting/debugging annotated libraries
37 How to create a new checker
37.1 How checkers build on the Checker Framework
37.2 The parts of a checker
37.3 Compiling and using a custom checker
37.4 Tips for creating a checker
37.5 Annotations: Type qualifiers and hierarchy
37.6 The checker class: Compiler interface
37.7 Visitor: Type rules
37.8 Type factory: Type introduction rules
37.9 Dataflow: enhancing flow-sensitive type refinement
37.10 Annotated JDK and other annotated libraries
37.11 Testing framework
37.12 Debugging options
37.13 Documenting the checker
37.14 javac implementation survival guide
37.15 Integrating a checker with the Checker Framework
38 Building an accumulation checker
38.1 Publications
39 Integration with external tools
39.1 Android
39.2 Android Studio and the Android Gradle Plugin
39.3 Ant task
39.4 Bazel
39.5 Buck
39.6 Command line, via Checker Framework javac wrapper
39.7 Command line, via JDK javac
39.8 Eclipse
39.9 Gradle
39.10 IntelliJ IDEA
39.11 javac diagnostics wrapper
39.12 Lombok
39.13 Maven
39.14 NetBeans
39.15 sbt
39.16 tIDE
39.17 Type inference tools
40 Frequently Asked Questions (FAQs)
40.1 Motivation for pluggable type-checking
40.2 Getting started
40.3 Usability of pluggable type-checking
40.4 How to handle warnings and errors
40.5 False positive warnings
40.6 Syntax of type annotations
40.7 Semantics of type annotations
40.8 Creating a new checker
40.9 Tool questions
40.10 Relationship to other tools
41 Troubleshooting, getting help, and contributing
41.1 Common problems and solutions
41.2 How to report problems (bug reporting)
41.3 Building from source
41.4 Contributing
41.5 Credits and changelog
41.6 License
41.7 Publications
