Returning Errors and Warnings
Providers use Diagnostics
to surface errors and warnings to practitioners,
such as contextual messages returned from Terraform CLI at the end of
command output:
In the framework, you may encounter them in response structs or as returns from functions or methods:
This is the most common form for Diagnostics: a slice that has one or more errors appended to it. This approach allows your provider to inform practitioners about all relevant errors and warnings at the same time, allowing practitioners to fix their configuration or environment more quickly. You should only append to Diagnostics slices and never replace or remove information from them.
The next section will detail the concepts and typical behaviors of
diagnostics, while the final section will outline the typical methods for
working with diagnostics, using functionality from the available
diag
package.
Diagnostic Concepts
Severity
Severity
specifies whether the diagnostic is an error or a warning. Neither Terraform, nor the framework, supports other severity levels. Use logging for debugging or informational purposes.
- An error will be displayed to the practitioner and halt Terraform's execution, not continuing to apply changes to later resources in the graph. We recommend using errors to inform practitioners about a situation the provider could not recover from.
- A warning will be displayed to the practitioner, but will not halt further execution, and is considered informative only. We recommend using warnings to inform practitioners about suboptimal situations that the practitioner should resolve to ensure stable functioning (e.g., deprecations) or to inform practitioners about possible unexpected behaviors.
Summary
Summary
is a short, practitioner-oriented description of the problem. Good
summaries are general—they don't contain specific details about
values—and concise. For example, "Error creating resource", "Invalid
value for foo", or "Field foo is deprecated".
Detail
Detail
is a longer, more specific practitioner-oriented description of
precisely what went wrong. Good details are specific—they tell the
practitioner exactly what they need to fix and how. For example, "The API
is currently unavailable, please try the request again.", "foo can only contain
letters, numbers, and digits.", or "foo has been deprecated in favor of bar.
Please update your configuration to use bar instead. foo will be removed in a
future release.".
Attribute
Attribute
identifies the specific part of a configuration that caused the
error or warning. Only diagnostics that pertain to a whole attribute or a
specific attribute value will include this information.
How Errors Affect State
Returning an error diagnostic does not stop the state from being updated. Terraform will still persist the returned state even when an error diagnostic is returned with it. This is to allow Terraform to persist the values that have already been modified when a resource modification requires multiple API requests or an API request fails after an earlier one succeeded.
When returning error diagnostics, we recommend resetting the state in the response to the prior state available in the configuration.
diag Package
The framework provides the diag
package for interacting with diagnostics.
While the Go documentation
contains the complete functionality, this section will highlight the most
common methods.
Working With Existing Diagnostics
Append
When receiving diag.Diagnostics
from a function or method, such as
Config.Get()
or State.Set()
, these should typically be appended to the
response diagnostics for the method. This can be accomplished with the
Append(in ...diag.Diagnostics)
method.
For example:
This method automatically ignores nil
or empty slice diagnostics and
deduplicates where possible.
HasError
The most typical form of diagnostics checking is ensuring that execution should
not stop due to encountering an error, potentially causing further confusing
errors or crashes. The HasError()
method
will check each of the diagnostics for error severity and return true if found.
For example:
In this example, you will note that we opted to check resp.Diagnostics
instead of diags
. Technically checking either is correct, however, checking
the response diagnostics can help ensure that any response will include the
expected diagnostics.
Creating Diagnostics
When working with logic outside the framework, such as interacting with the
vendor or net/http
library to make the actual calls to manage infrastructure
or creating custom plan modifiers and validators, it will be necessary to
create diagnostics. The diag
package provides helper methods and allows
custom abstractions as described below.
To craft the summary of a diagnostic, it is recommended to use a concise title or single sentence that immediately can allow the practitioner to determine the error cause and when it occurred.
To craft the details portion of diagnostics, it is recommended to provide practitioners (and potentially you as the maintainer) as much contextual, troubleshooting, and next action information as possible. These details can use newlines for easier readability where necessary.
For example, with the top line as a summary and below as details:
AddError and AddWarning
When creating diagnostics that affect an entire data source, provider, or
resource, and where a diag.Diagnostics
is already available such as within
a response type, the AddError(summary string, detail string)
method
and AddWarning(summary string, detail string)
method
can append a new error or warning diagnostic.
For example:
AddAttributeError and AddAttributeWarning
When creating diagnostics that affect only a single attribute, which is
typical of attribute-level plan modifiers and validators, the
AddAttributeError(path path.Path, summary string, detail string)
method
and AddAttributeWarning(path path.Path, summary string, detail string)
method
can append a new error or warning diagnostic pointing specifically at the
attribute path. This provides additional context to practitioners, such as
showing the specific line(s) and value(s) of configuration where possible.
For example:
Consistent Diagnostic Creation
Create a helper function in your provider code using the diagnostic creation functions available in the diag
package to generate consistent diagnostics for types of errors/warnings. It is also possible to use custom diagnostics types to accomplish this same goal.
The diag
package provides these functions to create various diagnostics:
Function | Description | |
---|---|---|
diag.NewAttributeErrorDiagnostic() | Create a new error diagnostic with a path. | . |
diag.NewAttributeWarningDiagnostic() | Create a new warning diagnostic with a path. | . |
diag.NewErrorDiagnostic() | Create a new error diagnostic without a path. | . |
diag.NewWarningDiagnostic() | Create a new warning diagnostic without a path. | . |
In this example, the provider code is setup to always convert error
returns from the API SDK to a consistent error diagnostic.
This enables calling code in the provider, such as:
Custom Diagnostics Types
Advanced provider developers may want to store additional data in diagnostics for other logic or create custom diagnostics that include specialized logic.
The diag.Diagnostic
interface that can be implemented with these methods:
To also include attribute path information, the diag.DiagnosticWithPath
interface can be implemented with the additional Path()
method:
In this example, a custom diagnostic type stores an underlying error
that caused the diagnostic: