If you have ever called an OpenAI-compatible API with streaming enabled and received... nothing, you are not alone. After debugging dozens of these cases (and building agent-stream-doctor to automate it), I keep seeing the same four failure modes.
1. Reasoning-only responses. Some models emit their entire answer inside a reasoning channel and mark the content channel as empty. The stream 'works' but your UI shows nothing. Always inspect the delta fields, not just the content.
2. Missing finish_reason. When a proxy truncates the final chunk, finish_reason disappears and many clients silently drop the message. Treat a missing finish_reason as a red flag, not a quirk.
3. Malformed SSE framing. Multi-byte UTF-8 split across chunk boundaries, or a proxy that rewrites 'data:' prefixes, will break parsers quietly. Log raw frames before parsing.
4. Truncated tool calls. Partial tool_call deltas that never merge into a complete call leave your agent hanging. Accumulate and validate arguments before executing.
The fix is always the same: observe the raw stream first, then reason about the protocol. That is exactly what my diagnostic toolkit does — check it out on GitHub.