4.2.5. Gateway and Refresh Failures

💡 First Principle: On-premises data gateway issues are common causes of refresh failures. Gateway version mismatches and connectivity problems are frequent culprits—and they're often the first thing to check.

Scenario: A Dataflow Gen2 refresh fails after running for approximately one hour. The error log mentions gateway timeout.

Gateway Troubleshooting Steps

1. Verify gateway version: Outdated gateways cause compatibility issues
2. Check gateway status: Ensure gateway service is running
3. Review network connectivity: Firewall, proxy configuration
4. Examine gateway logs: Detailed error information
5. Check source availability: a refresh that fails at the same time every night often collides with the source's maintenance or backup window—move the schedule

• Supported versions: Dataflow Gen2 requires a currently supported gateway—at minimum one of the last six released versions.
• One-hour OAuth2 limit: with OAuth2 credentials the gateway can't renew access tokens, so refreshes running longer than an hour fail (InvalidConnectionCredentials / AccessUnauthorized).

⚠️ Exam Trap: Assuming long-running failures are data issues. Gateway timeouts often cause failures after extended processing. Questions about "refresh fails after one hour" or "gateway-related errors" are testing whether you check gateway version first.