DEV Community: Mintlify

Debugging a mysterious HTTP streaming issue

Nick K — Tue, 05 Aug 2025 17:52:40 +0000

We recently encountered a frustrating issue with HTTP response streaming at Mintlify. Our system uses the AI SDK with the Node stream API to forward streams, and suddenly things stopped working properly. The symptoms were confusing: streaming worked perfectly with cURL and Postman, but failed completely with node-fetch and browser fetch.

Initial Investigation

Our first hypothesis centered around stream compatibility issues. We suspected the problem might be related to how the AI SDK responds using web streams versus Node streams, particularly around HTTP/2 compliance. Web streams have known issues with HTTP/2, while Node streams are compliant.

The Cloudflare Worker Bandaid

While investigating, we discovered an odd workaround. We set up a Cloudflare worker as middleware between our server and clients:

// Cloudflare Worker that acts as a CORS-enabled streaming proxy
export default {
  async fetch(request, env, ctx) {
    // Handle preflight CORS requests
    // ....

    // Extract request body for non-GET requests
    const body = ["GET", "HEAD"].includes(request.method) ? null : request.body;

    // Create headers that mimic a real browser request
    // ....

    // Forward the request to the target URL
    const response = await fetch(request.url, {
      method: request.method,
      headers: proxyHeaders,
      body: body,
    });

    // Copy response headers and enable CORS
    const responseHeaders = new Headers(response.headers);
    responseHeaders.set("Access-Control-Allow-Origin", "*");

    // Create streaming response to handle large payloads
    const { readable, writable } = new TransformStream();
    response.body?.pipeTo(writable);

    return new Response(readable, {
      status: response.status,
      statusText: response.statusText,
      headers: responseHeaders,
    });
  },
};

This worker simply received the stream and responded with it. Somehow, this completely fixed the issue, which made no sense to us at the time.

Ruling Out HTTP Versions

We quickly invalidated our HTTP/1 vs HTTP/2 suspicion by using cURL with the --http1.1 flag. Even when making HTTP/1 requests, things streamed properly. Throughout the entire debugging process, cURL consistently worked as expected.

Header Stripping Suspicions

One thing that stuck out was that our egress systems (ALB and Cloudflare) were stripping these headers:

'Transfer-Encoding': 'chunked',
'Connection': 'keep-alive',
'Content-Encoding': 'none',

Since browsers frequently have issues with these headers, and given that Postman and cURL worked while node-fetch and browser fetch didn't, we thought this might be the culprit.

Learning About Dynamic Responses

During this investigation, I learned more about "dynamic" responses and HTTP streaming in general. We explored whether an egress proxy was buffering the entire response to assign a content-length header, but that wasn't happening. It was valuable to develop better intuition around what HTTP streaming actually means.

The Breakthrough

After about 3 hours of making no progress, only Lucas made any headway. His previous Cloudflare experience gave him the intuition that a worker might fix the issue, which led to our temporary solution.

We implemented the patch fix and went to lunch, but had to deal with another issue: changing the IP to the Cloudflare worker triggered our IP-based rate limiter. After fixing that, we called it a day around 8pm.

Later that night, Lucas had an epiphany. Thinking about why cURL worked but fetch didn't, he consulted Claude about the differences between these tools. Claude walked him through a crucial insight: when Lucas examined the request headers, he noticed that cURL wasn't sending an Accept-Encoding header by default, while browsers always do. This missing header was the red flag that led Claude to explain that "cURL doesn't allow compressed responses without the --compressed flag."

As Claude pointed out, this behavior difference is key:

Browser requests include Accept-Encoding: gzip, deflate, br by default
cURL requests omit Accept-Encoding unless you use the --compressed flag
Without the Accept-Encoding header, servers won't compress the response

Bingo. The problem was compression.

The Solution

Lucas went into the Cloudflare dashboard, disabled compression, and everything worked perfectly. A simple solution to what had been a very annoying problem causing 10+ second latency on requests.

The Embarrassing Realization: A Familiar Problem in Disguise

This was embarrassingly familiar. Denzell and I had actually dealt with this exact issue before at Trieve, fixing it in PR #2002: remove compression for chat routes. The reason we didn't immediately recognize it was what I call "magic obfuscation" - when you've fixed something before but the context makes it unrecognizable.

In fact, Mayank, another team member at Mintlify who worked with Trieve from the customer side, had discovered a similar streaming issue with this message:

hey folks! were there any changes to the message apis yesterday? streaming doesn't seem to be working as intended. maybe github.com/devflowinc/trieve/pull/1999/files?

The key difference was visibility. Since Trieve is source available, Mayank could look at recent commits and quickly identify the issue. In our current Mintlify case, we had no such visibility into what changed, which made the debugging process exponentially more difficult.

When Cloudflare's Magic Becomes a Nightmare

The strangest part is that streaming worked correctly one day and stopped working the next, without any changes on our end. ALB configuration stayed the same, Cloudflare wasn't touched, and none of our code changed. Somehow, Cloudflare had silently enabled compression, and we have no idea why.

This highlights a fundamental issue with Cloudflare's approach to infrastructure management. While their "intelligent" defaults and automatic optimizations can be helpful for simple use cases, they create serious problems for production systems that require predictable behavior. The fact that a critical setting like compression can change without explicit configuration updates makes debugging nearly impossible.

In a properly designed infrastructure-as-code environment, this issue would have been immediately obvious. A git diff would show exactly when compression was enabled, by whom, and why. Instead, we spent hours chasing ghosts because Cloudflare's dashboard-driven configuration model obscures the audit trail of changes.

This isn't just about compression—it's about the broader pattern of "helpful" automation that removes visibility and control from engineering teams. When debugging production issues, the last thing you want is uncertainty about whether your infrastructure configuration matches what you deployed.

Lessons Learned

Compression breaks HTTP streaming - This is now permanently etched in my brain
cURL vs fetch behavior differences - cURL doesn't allow compressed responses without --compressed flag
Cloudflare workers as debugging tools - Sometimes adding middleware can help isolate problems
Source availability matters - Having access to change logs makes debugging much easier
Team knowledge sharing - Lucas's Cloudflare experience was crucial to finding both the workaround and the real solution

If I'm ever on a team using Cloudflare again, we'll make sure compression is disabled for any HTTP streaming endpoints from day one.

Breaking down common writing mistakes in documentation

Tiffany Chen — Fri, 24 Jan 2025 19:16:27 +0000

Good documentation just feels right, while bad docs leave you frustrated—but pinpointing what went wrong can be tough.

We spoke with Brody Klapko, Technical Writer at Stash, to discuss some common pitfalls that distinguish great technical docs from the rest, and how to avoid them. With over 10 years of experience in the industry, Brody's background includes roles as an early technical writing hire at Uber and Stripe, and more recently at Stash.

Here are common pitfalls that impact your docs:

Mixing content types
Unclear audience
Fundamental quality issues like spelling errors
Using docs as a band-aid for product

Let’s dig into each one.

Clarify purpose with the Diataxis framework

Mixing content types is a hidden killer. It’s when you find a lengthy paragraph in an API reference guide, or stumble upon a complex diagram when you're just trying to set up an SDK.

Documentation needs to be organized around the specific goal you're trying to help the user achieve. If they're looking to complete a task, long paragraphs of context just slow them down.

To focus your content, leverage the Diátaxis framework.

What is the Diataxis framework?

The Diátaxis framework categorizes documentation into four distinct types, helping you align content with user needs and goals.

Why and how to apply the framework

Defining content types helps you plan documentation with a clear purpose and makes it easier for users to find what they need.

Start by assigning each page a specific type—tutorial, how-to guide, explanation, or reference—before writing. This clarity ensures that your content matches your audience's goals. For multi-product companies, consider organizing by product at the top level and by content type within each product.

A key principle of the framework is learning through practice. You don’t need to fully understand it to start using it—try applying an idea that fits your current work, see how it works, and adjust as needed.

Always know who you’re writing for

Similar to defining content types, you should always know the intended audience of your documentation. Trying to write a single set of docs for multiple audiences—like technical and non-technical users—often leads to compromises that don’t fully satisfy either group.

Identify your top-priority audience and use that to guide your writing. For example, if your primary audience is developers, you might prioritize detailed API references and code samples over step-by-step guides. Conversely, if your audience includes less technical users, you might focus on high-level overviews and visual aids to convey concepts clearly.

Communicating these priorities internally is equally important. When everyone understands which audience is prioritized, it reduces friction in decision-making. Audiences can also shift as the product evolves, especially at startups, so it’s important to regularly revisit and align on who your primary users are.

Attention to quality pays off

Spelcheck please

Grammatical and spelling errors may seem small, but they’re the biggest indicator of quality. Mistakes can undermine trust, leaving readers with doubts about both your documentation and the product.

Also, avoid exclamation points. While not grammatically wrong, they can undermine professionalism and introduce unintended emotion.

Use screenshots sparingly

While screenshots can be helpful, use them sparingly—they quickly become outdated and erode user trust. Limit screenshots to showing users the starting point of a flow, letting your product UI guide the rest.

In some cases, demos with tools like Arcade are more effective. They provide clearer guidance by showing the GUI in action and offering context that static screenshots can't.

Design really matters

While readability is key, the overall look and feel can significantly impact user experience.

A clean sidebar, readable color schemes, and a consistent layout make a world of difference in user experience. If the design feels cluttered or hard to read, even the best content will lose its impact.

Beautiful documentation not only improves usability but also instills confidence in your docs and brand.

Docs are an accelerant, not a crutch

While great docs can help users navigate complexity, they aren’t a substitute for thoughtful design. If a workflow in your GUI takes 13 steps to complete, your docs can’t reduce that to three—they can only explain the process as it exists. In fact, documentation often highlights product complexity, exposing shortcomings in a very public way.

Over-reliance on documentation to “fix” a product can lead to frustration for both users and the teams tasked with maintaining the docs. That’s also why it’s crucial to align expectations internally with product & engineering—being on the same page about what documentation can and cannot solve helps set realistic goals and ultimately provide a better customer experience.

Treat documentation as a complement to a well-designed product, not a patch for its challenges.

Measure success with qualitative and quantitative feedback

Once you've worked to avoid common documentation mistakes, you'll want to measure your success. However, success depends on the context of your product and docs.

People typically track metrics like support tickets, page views, or time on page, but it might not paint the full picture. More page views may indicate users are running into errors and seeking help. Similarly, longer time on page might suggest users are struggling to find answers.

To assess your documentation's effectiveness, here are some questions to consider:

Where are users getting stuck? Is it an issue with the docs or the product?
How long does it take users to go from registering to making their first API call in test or prod?
What are users searching for in your docs? Do relevant pages exist for these searches?
What do users want more of in your docs?

To track documentation success, balance quantitative data with qualitative feedback. Collect input from users via feedback tools or customer-facing teams to guide future improvements.

Never forget, docs sell your product

Docs play a vital role in sales, adding credibility to your product and influencing decisions.

Even though technical docs aren’t written like sales materials, they’re often a key touchpoint for prospective users. Strong documentation builds trust and supports sales and marketing by allowing users to explore what’s possible. Go-to-market and documentation teams should collaborate and review how documentation can better support your company’s growth.