# Common troubleshooting and recipes
Source: https://speakeasy.com/docs/terraform/customize/common-troubleshooting

When generating Terraform providers from OpenAPI documents, you might
encounter cases where your API's structure doesn't naturally fit Terraform's
resource-oriented approach. These differences typically occur because APIs
aren't always designed with Terraform's infrastructure management style in
mind.

Speakeasy's generator identifies these design differences and offers extensions
and customization options to address them. This enables you to produce
effective Terraform providers, even when your API doesn't initially match
Terraform's requirements, simplifying what might otherwise be challenging
configuration tasks.

## Fixing common API issues

### Impedance mismatch errors

An impedance mismatch error happens when Speakeasy's generator finds properties
with different data types that need to be combined into one. This error means
the data types don't match up correctly across API operations (such as between
request and response data or across different operations for the same entity),
which can cause problems in the Terraform provider being created.

A typical impedance mismatch scenario occurs in the following situation:

- A request takes a UUID string for task assignment:

    ```json filename="request.json"
    {
      "taskId": "12345",
      "assignee": "user-uuid-1"
    }
    ```

- The response returns a full user object for that assignee:

    ```json filename="response.json"
    {
      "taskId": "12345",
      "assignee": {
        "id": "user-uuid-1",
        "name": "Alice Johnson"
      }
    } 
    ```

When the generator attempts to merge these properties, it detects that it
cannot reconcile the different data types (string vs object) and yields an
impedance mismatch error.

### How to fix an impedance mismatch error

Speakeasy includes built-in extensions to help fix impedance mismatch errors.
You can use these solutions to adjust either the request or the response data:

#### Option 1: Override the property name

Use `x-speakeasy-name-override` to give the mismatched properties different
names so they no longer attempt to merge:

```yaml filename="openapi.yaml"
TaskRequest:
  type: object
  x-speakeasy-entity: Task
  properties:
    taskId:
      type: string
    assignee:
      type: string
      x-speakeasy-name-override: assigneeId # Override the name to avoid merging
```

With this approach, the additional data (stored in the `assignee` response
field) is still available to Terraform consumers. However, there may be a
loss of drift detection when Terraform updates the resource's state during the
read operation.

**Note:** You can also use `x-speakeasy-name-override` to rename the conflicting
property (in this case, "assignee") in the response schema to achieve the same
effect. The key is to prevent a type collision between request and response.

#### Option 2: Ignore the mismatched property

Use `x-speakeasy-ignore` to exclude the problematic property from generation:

```yaml filename="openapi.yaml"
TaskResponse:
  type: object
  x-speakeasy-entity: Task
  properties:
    taskId:
      type: string
    assignee:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      x-speakeasy-ignore: true # Ignore this property in the response
```

This approach resolves the impedance mismatch by removing the
conflicting property altogether. However, this also means that the
property is no longer tracked in Terraform state.