401 Unauthorized loop caused by cached expired basic-auth credentials in Dart HttpClient

Expected behavior: no automatic invalidation

Dart's dart:io HttpClient does not discard cached basic-auth credentials after a server returns 401 Unauthorized. Credentials supplied via addCredentials or an authenticate callback are applied when the server challenges, and the client treats a 401 that follows an authenticated attempt as a server-side rejection — not as a signal to purge stored credentials. The SDK documents credential handling as the caller's responsibility, so the client will not silently decide whether the credentials are permanently invalid or transiently rejected.

This means the repeat-authentication loop is almost always a property of your own retry logic, not of an internal cache being mis-managed. If your code unconditionally re-adds the same expired credentials on every 401, the client will faithfully resend them, generating unnecessary traffic and, in long-running services, a potential denial-of-service pattern against your own backend.

Breaking the loop

Since the SDK provides no automatic invalidation mechanism, implement explicit invalidation in your application layer:

• Track failures per origin or realm: Count consecutive 401 responses. If a 401 arrives after credentials were already sent, stop retrying instead of resending the same header.
• Invalidate your own credential store: On a post-authentication 401, clear the cached credentials and surface the failure to whatever component owns credential refresh (token renewal, re-login flow).
• Gate the authenticate callback: Ensure your authenticate implementation checks credential freshness before responding to a challenge, rather than blindly returning the stale password.

Should the SDK add automatic invalidation?

The explicit model is defensible: when to discard credentials, how many retries to allow, and how to scope invalidation by realm are policy decisions that vary by application. Embedding one policy in the SDK would be wrong for many use cases. That said, a convenience helper (for example, a failure-counting credential wrapper) could reasonably be proposed through the Dart SDK issue tracker. Note that behavior around authentication callbacks can vary across SDK releases, so confirm against the version you actually deploy and check the changelog for any credential-invalidation additions.

Verification

To confirm where your loop originates, point HttpClient at a test server that issues a 401 challenge followed by a second 401 after credentials, and log the outgoing Authorization headers. If the header is identical across cycles, the loop is in your retry path, not in HttpClient internals. Add a per-origin 401 counter to your client wrapper and confirm the loop stops once invalidation triggers. Finally, if credentials are sent over plaintext HTTP, switch to HTTPS first — cache behavior is irrelevant if the credentials are exposed on the wire.