// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[validation-problem]]
= Dealing with validation problems

This page summarizes the different task (or in general work) validation problems that Gradle reports and provides guidance for fixing them.

[[invalid_use_of_cacheable_annotation]]
== Invalid use of cacheable annotation

This error indicates that you have annotated a type with `@CacheableTransform` on something that is not an artifact transform, or `@CacheableTask` on something which is not a `Task`.

The solution is to remove the annotation.

For tasks, the annotation to use is `@CacheableTask`.
For artifact transforms, the annotation to use is `@CacheableTransform`

[[missing_normalization_annotation]]
== Missing normalization annotation

This error occurs whenever a task or artifact transform is cacheable and that a file or file collection input property isn't declaring how it should be normalized.
Normalization tells Gradle if, for example, the absolute path of input files matter or if only the contents is relevant.
If you don't declare the normalization strategy, outputs of the task cannot be reused between machines or between different locations on the same machine.
In short, without normalization, caching is highly ineffective.

To fix this problem, you need to declare a normalization strategy, by applying one of the following annotations:

- link:{javadocPath}/org/gradle/api/tasks/PathSensitive.html[`PathSensitive`]
- link:{javadocPath}/org/gradle/api/tasks/Classpath.html[`Classpath`]
- link:{javadocPath}/org/gradle/api/tasks/CompileClasspath.html[`CompileClasspath`]

[[value_not_set]]
== Required value isn't set

This error indicates that a property expected a value but none was provided.
By default, Gradle properties are _required_, that is to say that if an input or output property isn't configured, either via a conventional value or explicitly by a build script, then Gradle will fail because it doesn't know what value to use when the task is executed.

To fix the problem, you must either:

- provide a value for this property explicitly (for example by configuring the task in your build script)
- or make the property optional by annotating it with link:{javadocPath}/org/gradle/api/tasks/Optional[`@Optional`]

[[cacheable_transform_cant_use_absolute_sensitivity]]
== Invalid use of absolute path sensitivity for an artifact transform

This error indicates that you have annotated an input of a cacheable artifact transform as sensitive to the absolute path.
However, artifact transforms are executed in isolation using their own workspace which, for example, is resilient to `clean` builds.
Even if the artifact transform result can't be shared via the build cache, using an absolute path sensitivity doesn't make sense.

To fix this problem, you must change the normalization strategy using one of those:

- link:{javadocPath}/org/gradle/api/tasks/PathSensitive.html[`PathSensitive`] (but not absolute)
- link:{javadocPath}/org/gradle/api/tasks/Classpath.html[`Classpath`]
- link:{javadocPath}/org/gradle/api/tasks/CompileClasspath.html[`CompileClasspath`]

[[artifact_transform_should_not_declare_output]]
== Invalid use of an output property on an artifact transforms

This error indicates that you have annotated a property of an artifact transform with an output annotation, which is not the correct way to register outputs for artifact transforms.

To fix this problem, you must remove the property and use the `TransformOutputs` parameter instead.

See link:{javadocPath}/org/gradle/api/artifacts/transform/TransformAction.html#transform-org.gradle.api.artifacts.transform.TransformOutputs-[TransformAction#transform(TransformOutputs)] for details.

[[ignored_annotations_on_field]]
== Invalid use of annotations on fields

This error indicates that you have a field annotated, but that there's no getter for this field.
Gradle will recognize annotations on fields _only_ if there's a corresponding getter.
If this getter is absent, the annotations have no effect whatsoever.

To fix this, you need to create a getter for this field.
We also recommend to annotate the getter instead of the field.

If you are using Groovy, it's likely that you unintentionally added the `private` modifier to a property declaration:

```groovy
@InputFile
RegularFileProperty inputFile // this is a public property

@InputFile
private RegularFileProperty inputFile // this is a field, remove the `private` modifier
```

[[ignored_annotations_on_method]]
== Invalid annotation on method

This error indicates that a annotation has been placed on an unexpected method.
In general, annotations like `@InputFiles` or `@OutputDirectory` need to be placed on a "property" method.
A property is defined by having a getter.

This causes Gradle to ignore the annotations, so they are typically not used in up-to-date checking or caching.

To fix this problem, you must remove the annotation, create a getter for the property you want to use and annotate the getter instead.

[[ignored_annotations_on_property]]
== Invalid annotation on property or field

This error indicates that an annotation intended for a non-property method has been unexpectedly placed on a field or a property method.
Only input and output annotations like `@InputFiles` or `@OutputDirectory` should be placed on a field or a "property" method.
A property is defined by having a getter.

This causes Gradle to ignore the annotations, so they are typically not recognized when Gradle is inspecting the class for important annotations.

To fix this problem, you must remove the annotation, or change the method to match the requirements of the annotation.

[[mutable_type_with_setter]]
== Mutable type with setter

This error indicates that a property of "mutable" type is also providing a setter.
Mutable types in Gradle include link:{javadocPath}/org/gradle/api/provider/Property.html[Property] or link:{javadocPath}/org/gradle/api/file/ConfigurableFileCollection.html[ConfigurableFileCollection].

For example, you wrote:

```groovy
class MyTask extends DefaultTask {
    private Property<Integer> x

    @Input
    Property<Integer> getX() { this.x }

    void setX(Property<Integer> x) { this.x = x }
}
```

However, mutable types like `Property` are designed to track dependencies and origin of values they are supplied with.
As a consequence, it is an error to make them overwritable, because Gradle will then be unable to tell where a property value comes from.

To fix this problem, you should either make your property final and remove the setter:

```groovy
class MyTask extends DefaultTask {
    @Input
    final Property<Integer> getX() = ...
```

You can also rely on Gradle's built-in capacity to inject final properties:

```groovy
abstract class MyTask {
    abstract Property<Integer> getX()
}
```

Then the value of the properties need to be configured via the mutation methods:

```groovy
myTask {
    x.set(123)
}
```

[[redundant_getters]]
== Redundant getters

This error indicates that a `boolean` property has both a `get` and an `is` getter method.
This is a problem because both getters can be annotated differently and Gradle cannot know which ones to use.

The solution to this problem is to get rid of one of the getters or to mark one of the getters with link:{javadocPath}/org/gradle/api/tasks/Internal.html[@Internal]

[[private_getter_must_not_be_annotated]]
== Annotations on private getters

This error indicates that you have annotated a _private_ getter with an input or output annotation.
Gradle doesn't consider private getters as inputs for up-to-date checking, which means that your annotations effectively are ignored.
It is important to fix because you might think that you have declared an input when it's not the case.

To fix this, either make the getter public, or annotate an existing getter instead, or create a new annotated getter.

[[private_method_must_not_be_annotated]]
== Annotations on private methods

This error indicates that you have annotated a _private_ method with an annotation that Gradle expects to query for.
Gradle won't be able to call the private method, which means that your annotations are effectively ignored.
It is important to fix because you might think that you have declared an annotated method which can't be used.

To fix this, either make the method public, or annotate another new or existing public method instead.

[[ignored_property_must_not_be_annotated]]
== Annotations on ignored properties

This error indicates that you have a property which is annotated with an annotation which tells Gradle to ignore it (for example link:{javadocPath}/org/gradle/api/model/ReplacedBy.html[`@ReplacedBy`] or link:{javadocPath}/org/gradle/api/tasks/Internal.html[`@Internal`]) but is also annotated with an input annotation (for example link:{javadocPath}/org/gradle/api/tasks/InputFile.html[`@InputFile`]).

This is an error because Gradle cannot determine if the property should actually be used for up-to-date checking, that is to say if it's actually an input or not.

To fix this, you must either:

- remove the input annotations from the property, or
- remove the ignoring annotation from the property.

A specific case of this error is combining `@Internal` and link:{javadocPath}/org/gradle/api/tasks/Optional.html[`@Optional`].
`@Internal` properties are already excluded from all validation, so adding `@Optional` is redundant and not allowed.
To fix this, remove the `@Optional` annotation.

[[conflicting_annotations]]
== Conflicting annotations

This error indicates that a property is annotated with conflicting annotations, that is to say annotations which have different, irreconciliable semantics.

For example, a property cannot be annotated both with `@InputFile` and `@OutputFile` at the same time.

To fix this problem, you need to understand the semantics of the different annotations and choose only one.

[[annotation_invalid_in_context]]
== Annotation is invalid in a particular context

This error indicates that a property was annotated with an annotation which is invalid in a particular context.
For example, it's in general possible to annotate a `DirectoryProperty` with `@OutputDirectory`, but this is invalid in the context of an artifact transform, because artifact transforms provide their own workspace.

To fix this problem, you must remove the property.

[[missing_annotation]]
== Properties without annotations

This error indicates that a property isn't annotated with an input or output annotation.
Therefore, Gradle doesn't know if this property represents an input, an output, or simply should be ignored.
As a consequence, up-to-date checking and caching won't work.

To fix this problem, you need to annotate the property with the appropriate annotation, for example `@InputDirectory` for a property representing an input directory, or `@OutputDirectory` for a property representing an output directory.

Alternatively, if the property is internal, that is to say that it shouldn't participate in up-to-date checking (it's not an input or an output), then you need to annotate it with link:{javadocPath}/org/gradle/api/tasks/Internal.html[@Internal].

NOTE: A common mistake is to annotate a property with only link:{javadocPath}/org/gradle/api/tasks/Optional.html[`@Optional`].
`@Optional` is a modifier annotation that must be combined with an input or output annotation such as `@InputFile`.
Using `@Optional` alone does not suppress validation — it results in this error.
If your intent is to exclude the property from up-to-date checking entirely, use `@Internal` instead.

[[incompatible_annotations]]
== Annotation is incompatible with the property type

This error indicates that for a specific kind of property, a modifier annotation doesn't make sense.
This is the case, for example, if the `@SkipWhenEmpty` is used on an output property.
Because there are no semantics associated with this combination, Gradle cannot deduce your intent.

To fix this, you most likely need to remove the conflicting modifier annotation or check that the actual property type is what you intended.

[[incorrect_use_of_input_annotation]]
== Incorrect use of the `@Input` annotation

This error indicates that a property is annotated with `@Input`, but that it should be annotated with `@InputFile` or `@InputDirectory` instead.

If you use the `@Input` annotation on a file-based property, Gradle wouldn't consider the file contents, or the directory contents, as inputs, as you might expect.

To fix this problem, you need to tell Gradle if the file property represents an input file, in which case you should annotate it with `@InputFile`, or a directory, in which case it should be annotated with `@InputDirectory`.
If what you really wanted to say is that the actual file path is an input, then you should return a `String` instead which corresponds to the absolute path of the file.


[[service_reference_must_be_a_build_service]]
== Property annotated with `@ServiceReference` is not a BuildService

This error indicates that a property annotated with `@ServiceReference` has a type that does not implement the `link:{javadocPath}/org/gradle/api/services/BuildService.html[BuildService]` interface.

Properties annotated with `link:{javadocPath}/org/gradle/api/services/ServiceReference.html[@ServiceReference]` are meant to hold references to <<build_services#build_services,shared build services>>.

[[implicit_dependency]]
== Implicit dependencies between tasks

This error indicates that you have a task which depends on another, but that no explicit or implicit dependency is declared between those two tasks.
As a consequence, the results of the build are dependent on the order of execution of tasks, often referred to "accidental dependencies between tasks".
Often, this is because you refer directly to the output file of another task instead of using the task directly as an input.

For example, imagine that you have a task which takes a `ConfigurableFileCollection` as an input and that you have declared a dependency on the `jar` task using this:

```
someTask {
    inputFile.from(jar.archivePath)
}
```

The `jar.archivePath` property is of type `File`, which doesn't carry any task dependency.
It means that if you call `someTask` _after_ `jar` has been called, the task will succeed, but if the jar is removed, for example, the task would fail.

To fix this, you can declare a `Property` as an input instead:

```
someTask {
    inputFile.from(jar.archiveFile)
}
```

The `jar.archiveFile` property is of type `Provider<RegularFile>` which properly carries task dependencies: Gradle will be able to know that the file is generated by the `jar` task.

It's actually even easier to add an implicit dependency to the task itself:

```
someTask {
    inputFile.from(jar)
}
```

In some cases, for producer tasks which don't use the <<lazy_configuration#lazy_configuration,configuration avoidance APIs>>, you can instead declare an _explicit dependency_ on the task:

```
someTask {
    dependsOn(producer)
    inputFile.from(producer.someFile)
}
```

In some cases, adding a dependency on the producing task is not desired, for example when the consumer generates reports for possible multiple tasks.
In this case you can introduce an <<controlling_task_execution.adoc#sec:ordering_tasks,ordering>> between the two tasks by using link:{groovyDslPath}/org.gradle.api.Task.html#org.gradle.api.Task:mustRunAfter(java.lang.Object++[]++)[Task.mustRunAfter()].

[[input_file_does_not_exist]]
== Input file doesn't exist

This error occurs whenever a file (or a directory) is declared as an input of a task, but at the moment the task is executed, the file (or directory) doesn't exist.

Usually, this hints at a missing task dependency: the file should exist _before_ the task is executed, which means that a dependent task wasn't executed.

The symptoms are similar to <<implicit_dependency>> except that in this case the task which creates the file hasn't been executed.

Please refer to the <<implicit_dependency>> section for possible solutions.
If the file isn't produced by another task, you may want to make sure that it exists before the task is called.
If what you want to declare is that it doesn't matter that the file exists or not when the task is executed, you can use `@InputFiles` that won't fail for non-existing inputs:

====
include::sample[dir="snippets/unused/tasks/customTaskWithMissingFileProperty/kotlin",files="build.gradle.kts[tags=task]"]
include::sample[dir="snippets/unused/tasks/customTaskWithMissingFileProperty/groovy",files="build.gradle[tags=task]"]
====

[[unexpected_input_file_type]]
== Unexpected input file or directory

This error indicates that a property expected a regular file as an input but that it was provided with a directory (or the other way around).

For example, if property is annotated with `@InputFile`:

```groovy
@InputFile
File getInputFile()
```

Then Gradle expects the input file to be a _regular file_. If the input is a directory, then validation fails.

To fix this problem, you have two options:

- either you made a mistake an provided a directory instead of a file in which case you just need to fix the input
- or the task should actually have used a directory as an input, in which case you need to change the type of the property to `@InputDirectory`

[[cannot_write_output]]
== Cannot write to an output file or directory

This error indicates that :

- an output directory cannot be written because the directory property which has been configured actually refers to a regular file (or something else than an actual directory).
- or that an output file cannot be written because the file property which has been configured actually refers to a directory.
- or the parent of the output location exists and is a file.

For example, you've set an output directory to `/some/path/file.txt` instead of `/some/path`.
It's also possible that you have configured an output directory like `/some/path` but that an ancestor `/some` is a regular file.

To fix this problem, make sure that the configured output is a directory (for properties which expect a directory) or a file (for tasks which expect a file).

[[cannot_write_to_reserved_location]]
== Cannot write to reserved location

This error indicates that you are trying to write a file to a location which is managed by Gradle only.
Typically, this happens whenever you're trying to write a file directly into an artifact transforms output directory.
If you did this intentionally, this is a mistake because those directories should never be written directly: all artifact transform writes should be performed within the artifact transform code itself.

If you didn't intend to write in this directory, you should simply setup your task to write in a different location.

[[unsupported_notation]]
== Unsupported notation in file inputs

This error indicates that a file, directory, collection of files, or a nested collection of files property, refers to an element that Gradle cannot convert to a file.

To fix this, look at the error message which indicates the list of supported file notations and make sure to pick one of them.

[[cannot_use_optional_on_primitive_types]]
== Invalid use of @Optional annotation on primitive types

This error indicates that a property of primitive type is also annotated with `@Optional`.
This is similar to `null` not being assignable to primitive types in Java.

To fix this problem, you have two options:

- remove the `@Optional` annotation
- or use the boxed type (e.g Integer instead of int) if you intend to make the property nullable


[[implementation_unknown]]
== Cannot use an input with an unknown implementation

This error indicates that a task uses a class as an input and Gradle cannot track the implementation of the class.
Gradle considers the implementation of the following classes as inputs to a task:

- the task class,
- the classes of the actions of the task,
- and the classes of nested inputs of the task, i.e. inputs annotated with `@Nested`.

There are two reasons why Gradle cannot track the implementation of a class:

- a non-serializable Java lambda was used to implement the class,
- or the class has been loaded by a classloader unknown to Gradle.

Using a Java lambda means that the bytecode uses invoke-dynamic instead of creating an actual sub-class.
The class for the invoke-dynamic instruction is generated at JVM runtime and Gradle cannot uniquely identify this class across different JVMs if the target functional interface is not serializable.
For task actions it is not a problem, because Gradle handles them in a special way.
On the other hand, for classes of nested inputs implemented by a non-serializable lambda Gradle does not support tracking.
As a workaround you can convert the lambda to an anonymous inner class or make the target functional interface serializable.

For the case where Gradle cannot track the implementation because it was loaded by a classloader unknown to Gradle, you can use Gradle's built-in ways to load the class.

[[disable_caching_by_default]]
== Missing reason for not caching

This warning indicates that the task or artifact transform action has not been marked as cacheable, though there also is no reason why it is not cacheable.
Task or artifact transform authors should always provide a reason why something is not cacheable by using the link:{javadocPath}/org/gradle/work/DisableCachingByDefault.html[`@DisableCachingByDefault`] annotation.

To fix the problem either annotate the work type with `@CacheableTask`/`@CacheableTransform` or `@DisableCachingByDefault(because = "...")`.

[[unsupported_value_type]]
== Unsupported value type

This message indicates that a task declares an input property with values of an unsupported type.

To address this, look at the message which indicates the list of possible solutions.

Please find below the list of unsupported value types:

`ResolvedArtifactResult`:: <<artifact_resolution.adoc#artifact-resolution, Mapping ResolvedArtifactResult as a task input>>
`java.net.URL`:: This type is not supported on properties annotated with @Input because up-to-date checks might to be inconsistent for this type, leading to incorrect build results.
This is caused by a known issue in Java where the serialization of `java.net.URL` is incorrect.
See the https://bugs.openjdk.org/browse/JDK-8075619[OpenJDK bug report] for more details.
To address this, we suggest to use `java.net.URI` instead.

[[unsupported_key_type_of_nested_map]]
== Unsupported key type of nested map

This error indicates that a nested map declares a key of an unsupported type.
Gradle uses the key to generate a name for the (sub)property.
Only allowing keys of certain types guarantees that these names are unique and well-formed. This is preferable to relying on `toString()` for producing such names.

To fix this problem, change the type of the key to `Integer` or `String` or an enum.

[[unsupported_nested_type]]
== Unsupported nested type

This error indicates that an unsupported type is annotated as nested.
Nested types are expected to either declare some annotated properties (which themselves are checked for annotations) or some conditional behaviour where capturing the type itself as input is important.
Types of the Java SE API, types of the Kotlin stdlib, and Groovy's GString are not supported, because they meet neither of those requirements.

To fix this problem, declare a nested type, e.g. `Provider<T>`, `Iterable<T>`, or `MapProperty<K, V>`, where `T` and `V` have some annotated properties or some behaviour that requires capturing the type as input.

