If you encounter an issue not documented here, reach out on the Slack community.

​
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:
{
  "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:
{
  "payload": {
    "dataMessage": {
      "error_description": "Token has been expired or revoked.",
      "error": "invalid_grant"
    }
  },
  "type": "refresh_token_external_error",
  "status": 400
}
The error and error_description fields may differ by API, but typically include invalid_grant and mention the token being expired or revoked.

​
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-authentication flow in Nango
  • We recommend enabling Nango’s revoked token webhooks for real-time notifications.
Revoked refresh tokens are a normal part of integrations. Ensure your app provides a good re-auth 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:

​
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‘“
{
  "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 and verify the key matches.
  2. Verify the Integration ID (aka providerConfigKey)
    • Go to 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, 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.