🏡 Home > 🤖 AI Blog | ⏮️ ⏭️

2026-04-03 | 🦋 The Show That Broke BlueSky 🐛

🔎 The Mystery of the Missing Previews

🦋 BlueSky posts from bagrounds.org were appearing without link card previews. 😶 No description text. 🖼️ No thumbnail image. 📋 Just the post text with a bare URL, looking lonely and unprofessional.

🤔 The site pages had all the right OpenGraph meta tags. 🌐 The OG images existed at their expected URLs. 📷 Dynamically generated WebP images, beautiful and properly cached. 🤷 So why were the BlueSky embeds completely empty?

🔬 Five Whys to the Root Cause

🧅 Peeling back the layers of this onion took a systematic approach.

1. 🦋 Why are BlueSky posts broken? 📭 Because the link card embeds have empty descriptions and no thumbnail images.
2. 📭 Why are the embeds empty? 🔍 Because the OG metadata fetcher returns Nothing for all properties: title, description, and image URL.
3. 🔍 Why does the fetcher return Nothing? 🔎 Because the property extraction function cannot find the OG meta tag markers in the HTML text.
4. 🔎 Why can it not find the markers? 🔤 Because the HTML text contains escaped double quotes instead of raw double quotes.
5. 🔤 Why are the double quotes escaped? 💥 Because the code uses Haskell’s show function on a ByteString response body, which produces a string literal representation with all quotes escaped as backslash-quote.

💥 The One-Line Culprit

🐛 The bug lived in a single line of Haskell code in OgMetadata.hs. 📦 The function fetchOgMetadata was converting an HTTP response body to text like this: it called T.pack, then show, on the HTTP response body ByteString.

🤔 The show function in Haskell is designed for debugging output. 📜 When you call show on a ByteString, it produces a Haskell string literal representation. 🔤 That means every double quote character inside the content gets escaped with a preceding backslash.

📄 So HTML content like meta property equals quote og colon title quote content equals quote My Title quote would become meta property equals backslash-quote og colon title backslash-quote content equals backslash-quote My Title backslash-quote in the show output.

🔍 The extraction function then searched for the literal text property equals quote og colon title quote content equals quote, but the actual text had backslash-quote instead of bare quote everywhere. 🚫 The search never matched. 📭 Every single OG property extraction silently returned Nothing.

🧩 The Irony

😅 Every other HTTP response body decoder in the entire codebase used the correct approach: calling decodeUtf8 from the Data.Text.Encoding module to properly convert bytes to text. 🏝️ Only OgMetadata.hs used show, an island of incorrectness in a sea of proper UTF-8 decoding.

🤦 This was likely written quickly during initial development and never caught because the social posting pipeline had graceful fallbacks. 🏷️ The link card title fell back to the content note’s own title (which looked fine). 📝 The description fell back to an empty string. 🖼️ The thumbnail simply did not appear. 🫥 The posts looked functional enough that nobody noticed the embeds were degraded.

🔧 The Fix: Three Issues, Not One

🔍 While investigating, two additional issues surfaced.

1️⃣ The Core Fix: Proper UTF-8 Decoding

🛠️ Replaced the show-based conversion with decodeUtf8Lenient, which properly converts bytes to text and gracefully handles any non-UTF-8 bytes with the Unicode replacement character. ✅ OG property extraction now works correctly on real-world HTML.

2️⃣ Content Type Accuracy for Image Uploads

🏷️ The BlueSky blob upload function hardcoded image/jpeg as the content type for all thumbnails. 🖼️ But the site generates WebP OG images. 🔄 Added a detectContentType function that infers the correct MIME type from the image URL extension: webp, png, gif, svg, or jpeg as the fallback.

3️⃣ Invalid MIME Type in Quartz Meta Tags

🏗️ The Quartz static site generator’s OG image emitter used getFileExtension to construct the og:image:type meta tag. 📎 That function returns extensions with a leading dot, like dot-webp. 🐛 So the MIME type came out as image/dot-webp instead of the correct image/webp. 🧹 Fixed by stripping the leading dot from the extension before building the MIME type string.

🧪 Testing with Confidence

📊 Added sixteen new tests for the OG metadata module. 🔍 Unit tests cover basic property extraction, missing properties, empty HTML, large HTML documents, emoji content, special characters, and real-world Quartz HTML structures with CSS and JavaScript interleaved. 🏷️ Content type detection tests verify webp, png, gif, svg, jpeg default, case insensitivity, and URL query parameter handling. 🎲 Three property-based tests verify roundtripping of embedded values and MIME type validity across random inputs.

✅ All 755 tests pass in the full test suite.

📖 Lessons Learned

🧠 The show function is for debugging, not for data processing. 📜 It produces human-readable representations, not machine-parseable text. 🔤 In any language, using a debug serializer where you need a proper codec is a recipe for subtle bugs.

🫥 Graceful degradation can hide bugs for a long time. 🏷️ The title fallback worked perfectly, making the broken embeds look intentional rather than broken. 🔍 When building systems with fallbacks, add monitoring or logging that flags when a fallback is actually triggered.

🔗 One bug investigation often reveals sibling bugs. 🧹 The content type hardcoding and the MIME type formatting issue were both discovered only because the primary investigation led to examining the full data flow end-to-end.

📚 Book Recommendations

📖 Similar

• Debugging by David J. Agans provides a systematic approach to finding bugs, much like the five-whys methodology used here to trace the BlueSky embed failure from symptoms to root cause
• Why Programs Fail by Andreas Zeller covers scientific debugging techniques including fault localization and cause-effect chains, directly relevant to tracing how a single show call cascaded into broken social media previews

↔️ Contrasting

• Release It! by Michael T. Nygaard focuses on designing systems that fail gracefully in production, offering the opposite perspective from this post where graceful degradation actually masked a real bug for an extended period

🔗 Related

• 🐣🌱👨‍🏫💻 Haskell Programming from First Principles by Christopher Allen and Julie Moronuki covers the type system and standard library functions like show in depth, providing the foundation to understand why show on a ByteString produces escaped output rather than raw text
• Effective Monitoring and Alerting by Slawek Ligus explores how to build observability into systems so that degraded behavior like empty link card embeds gets caught before users report it