hashicorp / hashicorp/terraform-plugin-sdk
Enhancements for Context Deadline Exceeded (Timeout) Errors
- Dominant language
- Go
- Stars
- 485
- Forks
- 244
- Avg merge
- 19h 57m
- Merged PRs (30d)
- 4
Description
### SDK version
```
v2.4.2
```
### Use-cases
Terraform provider resources can have the context timeout expire for a variety of non-trivial reasons:
* API code in the Terraform resource that automatically retries without returning (e.g. on HTTP status code 429 or 5xx type errors)
* Incorrect timeout handling in the Terraform resource
* Misconfigured customizable timeouts in the practitioner's configuration
Go's `context` package returns this as a [`DeadlineExceeded` error](https://go.googlesource.com/go/+/go1.15.6/src/context/context.go#161) with a terse message: `context deadline exceeded`. If the resource logic does not add any additional error messaging to provide contextual clues about what was happening or the timeout occurs at an awkward time in the resource logic, this will surface to the Terraform CLI as:
```
Error: context deadline exceeded
```
Which is likely very confusing for practitioners to know what the issue is or how to resolve it given that it does not match any Terraform terminology as defined in the [Terraform Glossary](https://www.terraform.io/docs/glossary.html). Even in the case that additional contextual information is added, this is still fairly confusing:
```
Error: error creating NetworkFirewall Firewall (tf-acc-test-6595592376741037247): RequestCanceled: request context canceled
caused by: context deadline exceeded
```
The `RequestCanceled: request context canceled` part of the error was added by AWS Go SDK v1 in this case, but it still does not provide any clues for practitioners about what to do.
### Attempted Solutions
Given these timeouts can occur at any point within resource logic (be it API calls, Terraform Plugin SDK calls, etc.) and resources can not opt out of the timeouts, all errors from the provider would need to be wrapped to capture this confusing message and potentially present a better version. This is a lot of work for provider development and is an issue that may not be obvious to developers until there are practitioner bug reports.
### Proposal
#### Proposal 1
Introduce a helper function, that can detect `context.DeadlineExceeded` type errors (e.g. via `errors.As()`) and return a more helpful diagnostic, e.g.
```
Error: Resource Timeout Exceeded
The resource reached a timeout before successful operation completion. This may represent a situation where unexpected API behavior occurred, where there is an incorrect implementation of timeouts in the resource, or where customizable timeouts may need to be adjusted in your configuration to match time expectations for the resource and type of operation.
Certain API operations may continue to run despite this error from Terraform, if the API operation is started and the resource timed out waiting for the operation status to change to completed.
Original Error: error creating NetworkFirewall Firewall (tf-acc-test-6595592376741037247): RequestCanceled: request context canceled
caused by: context deadline exceeded
```
Considerations:
* This wrapper must be on an `error` type before it is converted to a `diag.Diagnostic` type _otherwise_ this wrapper would need to do string based matching on the `Summary` / `Details`. That text-based matching could be avoided if `diag.Diagnostic` supported some form of `OriginalError` field or something.
#### Proposal 2
Automatically wrapping resource functions with Proposal 1 in the SDK. This would mean that provider developers do not need to do anything to get the "enhanced" error message.
Considerations:
* Considerations of Proposal 1
* I'm not sure if the SDK would be able to distinguish between its own context deadline error or if a sub-context was created and its deadline returned the error
* Introduces SDK "magic", which would need to be weighed in terms of user experience
### References
- https://www.terraform.io/docs/glossary.html
- https://github.com/hashicorp/terraform-provider-time/issues/19
Contributor guide
Assessment
This issue has not been assessed yet.