Troubleshooting the Terraform Provider

Existing OCI resources might be destroyed and re-created when Terraform configurations attempt to update a resource property that is not updatable. Terraform warns you when changes will destroy a resource. Always run terraform plan before applying changes to see what resources will be affected. See Destructive Changes for more information.

Sometimes, an update to an OCI resource should force the resource to be destroyed and re-created, but another resource's dependency on the resource disallows the operation.

For example, you might want to make an update to an oci_core_instance_configuration resource, but an instance pool uses that instance configuration. The instance configuration cannot be deleted because the instance pool references it in a required argument.

To work around this type of behavior, you can use the lifecycle and create_before_destroy meta-arguments in the resource block.

In this example, Terraform creates a second oci_core_instance_configuration resource that includes your updates, then assigns the new instance configuration to the related instance pool. Finally, Terraform destroys the original instance configuration. For example:

resource "oci_core_instance_configuration" "test_instance_configuration" {
...

 lifecycle {
    create_before_destroy = true
  }
}

See The lifecycle Meta-Argument and Destructive Changes for more information.

You can prevent an OCI resource from being destroyed by including the lifecycle and prevent_destroy = true meta-arguments in the resource block of your Terraform configuration file. The following configuration, for example, results in an Object Storage bucket that cannot be destroyed:

resource "oci_objectstorage_bucket" "test_bucket" {
  #Required
  compartment_id = var.tenancy
  name = "test"
  namespace = "exampleNamespace"

  lifecycle {
    prevent_destroy = true
  }
} 

This meta-argument prevents the use of terraform destroy. Because certain configuration updates require resources to be destroyed before they can be applied, this setting can make some updates impossible to apply as well. In this example, name is a property that cannot be updated without destroying and re-creating the resource. Therefore, you cannot update the name of the bucket without removing or changing the lifecycle meta-argument.

See The lifecycle Meta-Argument for more information.

Many Oracle Cloud Infrastructure resources managed by the OCI Terraform provider accept configuration arguments that are optional. Once set, whether during resource creation or a subsequent update, these arguments cannot be unset by passing an empty string or removing the argument from the configuration. Attempts to unset these arguments are ignored by Terraform.

Terraform v0.14 and later might require that you replace global variables in your configuration files with a combination of local variables and triggers. To reference a trigger in lifecycle and ignore_changes meta-arguments and avoid executing the configuration on subsequent Terraform apply operations, reference the trigger as follows:

resource "null_resource" "exampleB" {
  depends_on = [null_resource.exampleA]
  triggers = {
    os_user = var.os_user
  }
  lifecycle {
    ignore_changes = [
      triggers["os_user"]
    ]
  }

By default, the Terraform provider does not delete a compartment when using the destroy command.

You must set the enable_delete argument to true for the provider to attempt to delete the compartment. For example:

resource "oci_identity_compartment" "test_compartment" {
    compartment_id = var.compartment_id
    description = var.compartment_description
    name = var.compartment_name

    enable_delete = true
}

If the Terraform CLI returns an error message like the following:

Error: Operation Timeout
Provider version: <provider_version>, released on <release_date>. This provider is <n> updates behind to current. 
Service: <service>
Error Message: timeout while waiting for state to become 'SUCCEEDED, FAILED, CANCELED' (last state: 'IN_PROGRESS', timeout: 15m)

Then the specified OCI service is indicating that the resource has not yet reached the expected state after polling for some time.

You may need to increase the operation timeout for your resource to continue polling for longer. See Operation Timeouts for details on how to do this.

If the Terraform CLI returns an error message like the following:

Error: Unexpected LifeCycle state
Provider version: <provider_version>, released on <release_date>. This provider is <n> updates behind to current. 
Service: <service>
Error Message: During deletion, Terraform expected the resource to reach state: TERMINATED, but the service reported unexpected state: RUNNING.
Resource OCID: exampleuniqueID
Suggestion: Please retry or contact support for help with service: <service>

Then the specified OCI service encountered an unknown error. Retry, or contact support regarding that service.

If the Terraform CLI returns an error message like the following:

Error asking for user input: 1 error(s) occurred:

* provider.oci: dial unix /var/folders/6r/8fk5dmbj4_z3sl0mc_y_fhjw0000gn/T/plugin811254328|netrpc: connect: no such file or directory

You are likely using a version of the OCI Terraform provider that is not compatible with the Terraform binary you have installed. For OCI Provider versions v3.x.x and above, a minimum Terraform version of v.0.10.1 is required.

If the Terraform CLI returns an error message like the following:

* provider.oci: ... dial tcp 134.70.16.0:443: i/o timeout

Then you may not have properly configured your proxy settings. The OCI Terraform provider supports http_proxy, https_proxy and no_proxy variables where the inclusion or exclusion lists can be defined as follows:

export http_proxy=http://www.your-proxy.com:80/
export https_proxy=http://www.your-proxy.com:80/
export no_proxy=localhost,127.0.0.1

If the Terraform CLI returns an error message like the following:

Error: Get https://iaas.<region>.oraclecloud.com/20160918/services: x509: certificate signed by unknown authority
  on ../modules/network/modules/main/main.tf line 3...

Ensure that Terraform is using trusted TLS certificates and the certificate chain is valid. See Terraform runs failing with "x509: certificate signed by unknown authority" error for more information. If using MacOS Catalina, refer to the MacOS section of the document for more specifics on resolving certificate issues.

If the Terraform CLI returns an error message like the following:

Warning: registry.terraform.io: 
This version of Terraform has an outdated GPG key and is unable to verify new provider releases.
Please upgrade Terraform to at least <version> to receive new provider updates.
For details see: https://discuss.hashicorp.com/t/hcsec-2021-12-codecov-security-event-and-hashicorp-gpg-key-exposure/23512

This message means that the Terraform registry is omitting the Terraform provider versions signed by a new GPG key. The Terraform CLI will install the last version of the OCI Terraform provider that it can successfully verify, which might not be the latest version.

To remove this message and ensure you can use the latest version of the OCI Terraform provider, upgrade the Terraform CLI to the latest maintenance release available for the major Terraform version you are using. For example, if you are using Terraform v0.12.21, upgrade to the lastest available version of v0.12.

If you are using modules and the Terraform CLI returns an error message like the following:

Error: 401-NotAuthenticated, The required information to complete authentication was not provided or was incorrect.

Verify that each module declares its own provider requirements. For more information, see Providers Within Modules.

Symptom: The Terraform CLI returns an error message such as the following:

Error: 401-NotAuthenticated
Provider version: <provider_version>, released on <release_date>. This provider is <n> updates behind to current.
Service: <service>
Error Message: The required information to complete authentication was not provided or was incorrect.
OPC request ID: exampleuniqueID
Suggestion: Please retry or contact support for help with service: <service>

Possible causes: Incorrect configuration.

Resolution: Verify the following.

• Correctly configured attributes:
  • user_ocid
  • tenancy_ocid
  • fingerprint
  • private_key_path - verify that it's pointing to a private key, and not the corresponding public key.
• The public key corresponding to private_key_path was added to the user account specified as user_ocid.
• The public and private key pairs use the correct format. For details, and for steps to generate keys, see Required Keys and OCIDs.
• The user account is part of a group with the appropriate permissions to perform the actions in the plan you're executing.
• The tenancy is subscribed to the region targeted in the plan.
• If you're using modules, verify that each module declares its own provider requirements. For more information, see Providers Within Modules.

If the Terraform CLI returns a message like this, it might indicate an issue with your environment:

Error: can not create client, bad configuration: did not find a proper configuration for tenancy

If your provider configuration includes an alias, your resources should explicitly specify the provider alias using provider = "oci.alias_name". If a resource does not use the alias to specify the provider, Terraform creates a default provider to use with such resources. The default provider loads configuration values from environment variables or the ~/.oci/config file. These values may differ from those used by your aliased provider and cause the configuration error.

Either remove the alias in your provider configuration, or ensure that every resource specifies the provider by the proper alias. Read more about using alias in the official Terraform documentation, and see Configuring the Provider for more information about how Terraform uses environment variables and the OCI config file.

If the Terraform CLI returns an error message like the following:

* Error: "field_name": this field cannot be set

You are likely using an older version of the OCI Terraform provider and the field you are trying to set was released in a later version. Use the following command to check your Terraform provider version.

terraform -version

The OCI Terraform provider documentation reflects the latest version.

If the oci_database_db_system being imported is missing a primary db_home, an empty placeholder for db_home is set in the Terraform state file. To keep configurations consistent with the imported state, add an empty placeholder for db_home to your configuration. For example:

# Add this placeholder into your oci_database_db_system configuration to indicate that the primary db home is empty. 
db_home {
 database { 
  admin_password = "" 
  } 
}

If the Terraform CLI returns an error message like the following when using resource discovery:

Failed to query available provider packages
 
Could not retrieve the list of available versions for provider hashicorp/oci:
the previously-selected version is no longer available

Then you can ensure that Terraform uses an existing local provider binary by specifying its location using the provider_bin_path environment variable. For example:

export provider_bin_path=/Users/user/go/bin/

Terraform attempts to download the latest version of the OCI Terraform provider when you use resource discovery.

Sometimes, the OCI Terraform provider can unexpectedly delete existing tag defaults from a resource when running terraform apply. This issue affects the Oracle-Tags automatic tag defaults in particular.

To work around this issue, you can add the ignore_defined_tags attribute to your provider block.

The ignore_defined_tags attribute allows you to list out the keys of the defined tags that Terraform will ignore as part of plan or apply. The ignore_defined_tags attribute can only be specified at the provider level, and has a maximum allowed size of 100. The tags provided in this attribute are ignored for all the resources in that Terraform file.

In the following example, "Oracle-Tags.CreatedOn" and "Oracle-Tags.CreatedBy" are the keys in the defined_tags map associated with a remote resource:

provider "oci" {
    ignore_defined_tags = ["Oracle-Tags.CreatedBy", "Oracle-Tags.CreatedOn"]
}

For more information, see Provider Definitions and refer to the related GitHub issue.

If the Terraform CLI returns an error message like the following:

Error: 400-InvalidParameter
Provider version: <provider_version>, released on <release_date>. This provider is <n> updates behind to current. 
Service: <service>
Error Message: <error_message>
OPC request ID: exampleuniqueID
Suggestion: Please update the parameter(s) in the Terraform config as per error message: <error_message>

Update the parameter specified in the error message in the Terrform configuration for the resource.

While using Terraform, you might encounter errors indicating that you have reached or exceeded the service limits for a resource. For example:

Error: 400-LimitExceeded
Provider version: <provider_version>, released on <release_date>. This provider is <n> updates behind to current. 
Service: <service>
Error Message: Fulfilling this request exceeds the Oracle-defined limit for this tenancy for this resource type.
OPC request ID: exampleuniqueID
Suggestion: Request a service limit increase for this resource <service>

To understand more about OCI service limits and how to request a limit increase, see Service Limits

If the Terraform CLI returns an error message like the following:

Error: 404-NotAuthorizedOrNotFound
Provider version: <provider_version>, released on <release_date>. This provider is <n> updates behind to current.
Service: <service>
Error Message: Authorization failed or requested resource not found.
OPC request ID: exampleuniqueID
Suggestion: Either the resource has been deleted or service <service> need policy to access this resource. Policy reference: <link>

Verify the user account is part of a group with the appropriate permissions to perform the actions in the plan you are executing. Refer to the policy reference for your service for more information.

If the Terraform CLI returns an error message like the following:

Error: 500-InternalError
Provider version: <provider_version>, released on <release_date>. This provider is <n> updates behind to current. 
Service: <service>
Error Message: Internal error occurred
OPC request ID: exampleuniqueID
Suggestion: The service for this resource encountered an error. Please contact support for help with service <service>

The service responded to the request from the Terraform provider with an internal error. If you contact support for this issue, reference the information in the message.