Ky.retry Pending: Unread Response Body Issue

Discover a subtle yet significant issue within the ky library where `ky.retry` can enter a pending state if the response body remains unread. This article delves into the root cause, its implications, and potential solutions, especially in Node.js environments.

Understanding the `ky.retry` Pending State

We all love libraries that simplify our lives, and `ky` is definitely one of them. Its ease of use and powerful features make it a go-to for making HTTP requests. However, as with any complex piece of software, sometimes we stumble upon unexpected behaviors. Recently, while integrating ky into one of our projects, specifically when implementing a response hook to handle 401 errors by refreshing access tokens, we encountered a peculiar problem. This involved the `ky.retry` mechanism hanging indefinitely, or entering a 'pending' state, under certain conditions. This behavior was particularly frustrating because it worked seamlessly in browser environments but manifested as timeouts in Node.js-based testing setups like Vitest. The core of the issue, we discovered, lies in how ky handles response streams when the body is not consumed. When the response body isn't read before a retry is initiated, the internal mechanisms responsible for canceling the response stream can get stuck, leading to the observed timeouts. This is a critical detail for developers relying on ky for robust error handling and retry logic, especially in server-side rendering (SSR) or other Node.js contexts where such timeouts can cripple application performance and test reliability. Our journey to pinpoint this involved diving deep into the ky source code and tracing the execution flow during these problematic retries. We found that the promise returned by the initial `cancel()` call on the response body could indeed hang forever if the body was never accessed. This is a behavior that might not be immediately apparent during typical browser-based development, where network conditions and execution contexts can differ significantly from a Node.js server environment. The implications of this pending state are far-reaching, potentially causing your application to freeze or your tests to fail due to unresponsiveness, making it crucial to understand and address this behavior.

The Root Cause: Unread Response Bodies

The crux of the problem emerges when a response hook, like the one designed to refresh a token on a 401 error, is triggered, but the response body itself is never read. In the provided code snippet, the hook intercepts a 401 response, attempts to refresh the token, and if successful, initiates a retry with updated headers. However, the original response object, from which the retry is initiated, has its body stream passed through without being consumed. This is where the issue lies. The ky library, in its internal handling of retries, attempts to cancel the ongoing response stream to clean up resources. When the response body has not been read at all, this cancellation process, particularly in a Node.js environment, can lead to a deadlock. We observed that the promise returned by `response.body?.cancel()` would remain in a pending state. This is contrasted with scenarios where the body *is* read, such as in many of ky's own unit tests. In those tests, the body is typically consumed (e.g., using `.json()`, `.text()`, or `.blob()`), which implicitly handles the stream cleanup. The problem surfaced in our Node.js environment (Vitest) because our hook, designed purely for error checking and token refreshing, did not need to read the response body. It only needed the status code and headers. This led to `response.bodyUsed` being `false` before the retry. The link to the `undici` ticket (`#4562`) further solidifies this hypothesis, suggesting that the underlying HTTP client in Node.js might have its own intricacies when dealing with unread response streams and cancellation requests. Understanding this distinction between browser and Node.js environments is key. While browsers might have different stream handling or garbage collection behaviors, Node.js, with its specific networking stack, can expose these unread stream issues more readily. The consequence is that the `ky.retry` call, instead of proceeding, gets stuck waiting for a cancellation that never resolves, effectively halting the request lifecycle and causing timeouts. This can be particularly problematic in applications that rely heavily on predictable request lifecycles and efficient resource management.

Code Example and Debugging Findings

Let's dissect the scenario with the provided code and debugging output. The response hook is designed to intercept responses. If a response status is 401 and it's not an excluded URL, it attempts to refresh the access token. Upon successful refresh, it creates a new `Request` object with an `Authorization` header set to the new token and then calls ky.retry(). The critical observation comes from the debugging logs during a failing test in a Node.js environment:

ky.request.bodyUsed: false
First call to clonedResponse.body?.cancel(): Promise { <pending> }
First call to response.body?.cancel(): Promise { <pending> }
Second call to clonedResponse.body?.cancel(): Promise { undefined }
Second call to response.body?.cancel(): Promise { undefined }

This output is highly informative. Firstly, ky.request.bodyUsed: false confirms that the response body was indeed never read. Then, the subsequent calls to response.body?.cancel() (and `clonedResponse.body?.cancel()`, suggesting internal cloning might also be affected) return promises that remain <pending>. This is the direct indication of the hang. The fact that a *second* call to `cancel()` eventually resolves (returning `undefined`) might suggest an internal retry or a different path being taken, but the initial `pending` state is the culprit for the timeout. In contrast, when this same logic is tested within ky's own test suite, these timeouts do not occur. The reason, as noted, is that the tests frequently involve reading the response body, for instance, using `await response.json()`. This action implicitly drains and closes the response stream, preventing the cancellation promise from hanging. This discrepancy highlights the sensitivity of the Node.js networking environment to unconsumed streams. The `undici` issue mentioned (#4562) further supports this, pointing to potential underlying issues in Node.js's HTTP client that could be triggered by this specific sequence of operations: receiving a response, not reading its body, and then attempting to cancel the stream during a retry operation. The debugging logs clearly illustrate the mechanical failure: the library tries to perform a cleanup action (canceling the stream), but the stream's state (unread) prevents this action from completing, leaving the retry operation in limbo.

Implications for Node.js and SSR

The implications of this `ky.retry` pending issue are particularly significant for Node.js applications, including those using Server-Side Rendering (SSR) or running in environments like Vitest. In these server-side contexts, network requests are fundamental, and unexpected delays or timeouts can have a cascading effect on performance and user experience. When a retry operation gets stuck in a pending state due to an unread response body, it doesn't just affect that single request; it can tie up server resources, leading to slower response times for other users or even complete unresponsiveness. For testing frameworks like Vitest, which rely on fast and predictable test execution, these timeouts mean that tests will fail, hindering the development workflow and potentially allowing bugs to slip into production. The behavior is exacerbated in SSR because requests are often made in sequence or in parallel to hydrate the initial page load. If one of these requests hangs due to the retry issue, the entire page rendering process can stall. Developers implementing robust error handling strategies, such as token refresh logic, need to be acutely aware of this potential pitfall. Relying solely on checking response status codes without consuming the body can lead to brittle implementations when deployed to Node.js. This means that architectural decisions around how your application handles API responses, especially error responses that trigger retry logic, need to account for the nuances of the underlying runtime environment. The difference in behavior between browsers and Node.js underscores the importance of testing integrations thoroughly in the target environment. What works flawlessly in a browser's development environment might present subtle, yet critical, issues when running on a server. This issue serves as a reminder that abstractions, while powerful, can sometimes mask environment-specific behaviors that require careful consideration.

Potential Solutions and Workarounds

Addressing the `ky.retry` pending issue requires a mindful approach to handling response streams, particularly when implementing retry logic in Node.js. The most direct workaround is to ensure that the response body is consumed, even if its content is not strictly needed for the current operation. By adding a line to read the body, you effectively signal to the underlying HTTP client that the stream handling can proceed to completion. A simple way to do this is by calling a method like `response.text()` or `response.arrayBuffer()` and then discarding the result. For example, within the response hook, after checking the status and before initiating the retry, you could add:

await response.text(); // Consume the body to prevent the stream from hanging

This ensures that the promise returned by `response.body?.cancel()` has a higher chance of resolving as expected. Another approach could involve exploring configuration options within ky or the underlying `undici` client, though documentation on specific stream cancellation behaviors in error scenarios might be scarce. If you have control over the server's API responses, ensuring that error responses (like 401s) have minimal or empty bodies can also mitigate the risk, though this is often not feasible. For libraries like ky, contributing to their ongoing development by reporting such issues and proposing solutions is invaluable. The linked `undici` ticket suggests that the Node.js core team is aware of related stream handling complexities. A more sophisticated solution within the hook might involve adding a timeout to the `cancel()` promise itself, although this wouldn't fix the root cause but rather provide a fallback mechanism to prevent indefinite hangs. However, the most robust and recommended solution, based on the findings, is to proactively consume the response body whenever a retry might be triggered, ensuring that the stream lifecycle is properly managed across different JavaScript runtimes. This practice aligns with the principle of explicit resource management and guarantees more predictable behavior in Node.js environments.

Conclusion: Prioritizing Body Consumption for Reliable Retries

In conclusion, the `ky.retry` pending state when response bodies are unread is a critical nuance to understand when working with the ky library, especially in Node.js environments. While ky is an exceptional tool for HTTP requests, this specific interaction highlights the importance of how response streams are managed. The core issue stems from the cancellation promise within ky's retry logic getting stuck when the response body hasn't been consumed. This is more pronounced in Node.js due to differences in stream handling compared to browsers. The most effective workaround is to ensure that the response body is always consumed within your response hooks, even if you don't need the data itself. By calling methods like `.text()` or `.arrayBuffer()`, you allow the stream to close properly, enabling the retry mechanism to function as expected and avoid timeouts. This proactive approach not only solves the immediate problem but also leads to more robust and predictable network request handling in your applications. Thorough testing in your target environment, whether it's a browser, Node.js server, or a testing framework like Vitest, is paramount to catching such environment-specific issues early. We hope this detailed explanation helps you navigate this potential pitfall and leverage ky's retry capabilities with confidence. For further insights into Node.js networking and stream handling, you might find the official **Node.js HTTP Client documentation** and the **Undici documentation** extremely useful resources.