> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Common issues

> Troubleshooting guide for frequent errors and how to fix them.

If you encounter an issue not documented here, reach out on the [Slack community](https://nango.dev/slack).

## I just run `nango migrate-to-zero-yaml`, can I change the folder structure?

Yes, you can change the folder structure. You can move files, zod definitions, types, rename files, folders, etc.
The results of the migration is just an example of how you can structure your project.

## I'm getting `ZodXX is missing the following properties` errors

If you are getting Zod errors, it's most likely because you are using a different version of Zod than the one we use in our CLI. We currently require zod `4.0.5`.

If you have an overrides in your package.json or something that is changing the version of Zod, you will need to remove that.

NB: `nango compile` will automatically update your dependencies to the version we use in our CLI.

## Token refresh error from the external API

Indications of the error:

* Nango logs may show:

```json theme={null}
{
  "error": {
    "message": "An error occurred during an HTTP call",
    "payload": {
      "error": {
        "code": "invalid_credentials",
        "payload": { [...] },
        "message": "The refresh limit has been reached for this connection."
      }
    }
  }
}
```

* Or in `Token refresh` log operations:

```json theme={null}
{
  "payload": {
    "dataMessage": {
      "error_description": "Token has been expired or revoked.",
      "error": "invalid_grant"
    }
  },
  "type": "refresh_token_external_error",
  "status": 400
}
```

<Note>
  The `error` and `error_description` fields may differ by API, but typically include `invalid_grant` and mention the token being expired or revoked.
</Note>

### How to debug

* This error means the external API (e.g., Google, Salesforce) rejected the refresh token as expired or revoked. Nango retries several times, but if the error persists, the credentials are considered permanently broken.
* The only solution is to ask the user to re-authenticate. See: [How to trigger a re-authorization flow in Nango](/guides/auth/auth-guide#re-authorize-an-existing-connection)
* We recommend enabling [Nango's revoked token webhooks](/guides/platform/webhooks-from-nango#auth-webhooks) for real-time notifications.

Revoked refresh tokens are a normal part of integrations. Ensure your app provides a good re-authorization experience for users.

APIs may revoke tokens for unpredictable reasons. Only investigate if you observe an unusual increase of connection revocations for an API. Achieving a 0% revocation rate is not realistic.

Known API-specific behaviors:

* Google: All tokens are revoked after 7 days if your OAuth app is in test mode ([detailed guide](https://www.nango.dev/blog/google-oauth-invalid-grant-token-has-been-expired-or-revoked)). To go to production, read our [guide for Google's OAuth app review](/api-integrations/google-shared/google-security-review).
* Salesforce: See [Salesforce refresh token issues](https://nango.dev/blog/salesforce-oauth-refresh-token-invalid-grant/).

## Connection not found (unknown\_connection / 404)

Indications of the error:

* Request failed with status code `404`
* code `unknown_connection`
* error message: "No connection matching the provided params of 'connection\_id' and 'provider\_config\_key'"

```json theme={null}
{
  "error": {
    "message": "Request failed with status code 404",
    "data": {
      "error": {
        "message": "No connection matching the provided params of 'connection_id' and 'provider_config_key'.Please make sure these values exist in the Nango dashboard [...]",
        "code": "unknown_connection"
      }
    }
  }
}
```

### How to debug

1. Confirm the environment and secret key
   * The `secretKey` in the API or SDK is specific to the environment. Make sure you pass the key that corresponds to the environment you are using (e.g., dev vs prod).
   * Open [Environment Settings > API Keys](https://app.nango.dev/dev/environment-settings#api-keys) and verify the key matches.

2. Verify the Integration ID (aka `providerConfigKey`)
   * Go to [Integrations](https://app.nango.dev/dev/integrations), open the integration, and copy the `Integration ID` exactly.
   * Ensure the value you send as `providerConfigKey` matches this ID.

3. Verify the Connection ID
   * Go to [Connections](https://app.nango.dev/dev/connections), find the connection, and copy its `Connection ID`.
   * Ensure the value you send as `connectionId` (header `Connection-Id` when using HTTP, or `connectionId` in the SDK) matches exactly.

## Related guides

* [Observability](/guides/platform/observability) - inspect logs and exported traces.
* [Auth guide](/guides/auth/auth-guide#re-authorize-an-existing-connection) - repair broken connections with re-authorization.
* [Token refreshing and validity](/guides/auth/token-refreshing) - understand refresh failures.
* [Webhooks from Nango](/guides/platform/webhooks-from-nango) - receive failure notifications.