Guides & Fixes

The specific bug, the specific error, the fix that isn't in the official docs yet.

All posts

Terminal window comparing Vitest 4's top-level bench import against Vitest 5's bench fixture destructured from test(), with the four removed benchmark config options listed in red

Guides & Fixes

Fix Vitest 5 bench No Longer Top-Level Export

Vitest 5 removes bench as a top-level export. Fix it by moving benchmarks into a test() context fixture instead.

Aug 13, 2026Read more →

A dark code editor style panel titled Vitest 5 migration guide - removed entrypoints, listing vitest/reporters, vitest/coverage, vitest/environments, and vitest/snapshot each mapped to their documented replacement

Guides & Fixes

Fix Vitest 5 Cannot Find Module vitest/reporters

Fix Vitest 5's module resolution failure on vitest/reporters and vitest/coverage. Vitest 5 removes eight subpath imports; use vitest/node instead.

Aug 13, 2026Read more →

vitest.config.ts diff showing clearMocks changing from its old false default to Vitest 5's new true default

Guides & Fixes

Fix Vitest 5 clearMocks Breaking Mock State

Fix Vitest 5's clearMocks: true default wiping mock call history between tests, and decide whether to restore it or fix the test.

Aug 13, 2026Read more →

Command-line diff showing vitest run from a subdirectory failing to find a parent config, fixed by adding an explicit --config flag

Guides & Fixes

Fix Vitest 5 Config Not Found in Parent Directory

Fix Vitest 5 no longer finding a vitest.config.ts in a parent directory when run from a subdirectory. Pass --config explicitly.

Aug 13, 2026Read more →

Vitest's documented expect.poll timeout error message, expect.poll() function didn't resolve in time, next to a code example passing the callback's new AbortSignal parameter to fetch

Guides & Fixes

Fix Vitest 5 expect.poll Timeout Error

Vitest 5 throws 'expect.poll() function didn't resolve in time.' on timeout instead of letting a late result pass. Here's the fix.

Aug 13, 2026Read more →

A dark code editor style panel titled vitest.config.ts - projects extends option, showing extends now defaults to true and listing what an inline project inherits automatically, with extends: false as the opt-out

Guides & Fixes

Fix Vitest 5 Projects Not Inheriting Root Config

Vitest 5's extends option defaults to true, so inline test.projects now inherit root plugins and setupFiles automatically. Fix it with extends: false.

Aug 13, 2026Read more →

Code diff showing test.sequential and describe.sequential calls replaced with the concurrent: false option in Vitest 5

Guides & Fixes

Fix Vitest 5 test.sequential Removed Error

Fix Vitest 5 removing test.sequential, describe.sequential, and the sequential option. Replace them with concurrent: false.

Aug 13, 2026Read more →

A dark code editor style panel titled vitest.config.ts - toThrow matcher change, contrasting Vitest 4's empty-message-only match against Vitest 5's match-any-error behavior with the fix below it

Guides & Fixes

Fix Vitest 5 toThrow('') Silently Passing Tests

Vitest 5 changes toThrow('') to match any thrown error, not just an empty message. Fix the silent false-pass with toThrow(/^$/) or toThrow().

Aug 13, 2026Read more →

Terminal window showing a Vitest test with an unawaited resolves.toBe assertion, annotated with Vitest 4's pass-with-warning behavior versus Vitest 5's fail behavior, next to the one-line await fix

Guides & Fixes

Fix Vitest 5 Unawaited Async Assertion Error

Vitest 5 fails tests outright on an unawaited async assertion instead of just warning. Here's why, and the one-line fix.

Aug 13, 2026Read more →

Terminal output showing Vitest's documented error: 1 call in calculator.test.ts was defined outside of the module's top level scope, pointing at a nested vi.mock call

Guides & Fixes

Fix Vitest 5 vi.mock Top-Level Scope Error

Fix Vitest 5's "defined outside of the module's top level scope" error thrown by vi.mock, vi.unmock, and vi.hoisted.

Aug 13, 2026Read more →

A dark comparison-matrix style cover listing Vitest 5.0 beta's breaking changes across three groups: mocking (vi.mock scope, clearMocks default flip), config (projects inheritance, parent-directory lookup), and assertions (expect.poll, async awaits, toThrow(''))

Guides & Fixes

Vitest 5.0 Beta Breaking Changes: Full Guide

Vitest 5.0 beta ships 10 breaking changes across mocking, config, and assertions. Full rundown, sourced to the official migration guide, plus fixes.

Aug 13, 2026Read more →

A terminal window showing the real Node.js error: Cannot find module satteri, reproduced under pnpm's default isolated node_modules linker

Guides & Fixes

Fix Astro 7 Cannot Find Package satteri Error (pnpm)

Fix Astro 7's Cannot find package satteri error under pnpm. Still open upstream, with a live-tested workaround using node-linker=hoisted.

Aug 5, 2026Read more →

A terminal window showing the real Astro warning: markdown.gfm and markdown.smartypants are deprecated, printed by the Container API even though the project never set either option

Guides & Fixes

Fix Astro 7's False markdown.gfm Deprecation Warning

Fix Astro 7's false markdown.gfm and markdown.smartypants deprecation warning from the Container API, and the version that fixes it.

Aug 5, 2026Read more →

A terminal window showing the real Vite build error: MISSING_EXPORT satteriCollectImagesPlugin is not exported by the @astrojs/markdown-satteri optional peer dependency

Guides & Fixes

Fix Astro 7 MISSING_EXPORT satteriCollectImagesPlugin

Fix Astro 7's MISSING_EXPORT satteriCollectImagesPlugin error from @astrojs/mdx. The real cause, and the version that already fixes it.

Aug 5, 2026Read more →

A terminal window showing the real Astro build warning: markdown.remarkPlugins, markdown.rehypePlugins, and markdown.remarkRehype are deprecated, pass them to unified from at astrojs slash markdown-remark directly instead

Guides & Fixes

Fix Astro 7 markdown.rehypePlugins Deprecation Warning

Fix Astro 7's markdown.rehypePlugins deprecation warning. The exact config fix, tested live against a real Astro 7 build.

Aug 5, 2026Read more →

A terminal window showing the real Vite/Rollup warning: Rollup failed to resolve import satteri from the @astrojs/mdx dist folder, most likely unintended because it can break your application at runtime

Guides & Fixes

Fix Astro 7 Rollup Failed to Resolve Import satteri

Fix Astro 7's Rollup failed to resolve import satteri error from getContainerRenderer. Real cause, and the exact @astrojs/mdx version already fixing it.

Aug 5, 2026Read more →

A code diff showing the fix for Astro 7's Satteri heading-ids plugin: collecting headings into a local array and assigning it once, instead of pushing directly onto the shared astro.headings array

Guides & Fixes

Fix Astro 7 Duplicate Heading IDs From Sätteri Bug

Fix Astro 7 Satteri duplicate heading entries when Starlight assigns its own IDs first. Confirmed fixed in this site's own installed version.

Aug 5, 2026Read more →

A terminal window showing the real error: Not implemented, thrown from PluginContextImpl.generateBundle when Astro's dev toolbar runs under Vite 8's Rolldown esbuild-compat shim

Guides & Fixes

Fix Astro Dev Toolbar 'Not Implemented' Crash

Fix Astro's dev toolbar crashing with a 'Not implemented' error under Vite 8's Rolldown esbuild-compat shim. Real workaround included.

Aug 5, 2026Read more →

A terminal window showing the real astro-mermaid warning: markdown.remarkPlugins, rehypePlugins, and remarkRehype are set, but your satteri processor doesn't run them

Guides & Fixes

Fix astro-mermaid Diagrams Breaking Under Astro 7

Fix astro-mermaid diagrams silently rendering as plain code under Astro 7's Satteri processor, and the version that fixes it.

Aug 5, 2026Read more →

A terminal window showing the real error: Missing field tsconfigPaths on BindingViteResolvePluginConfig.resolveOptions, thrown by @tailwindcss/vite under Vite 8's Rolldown resolver

Guides & Fixes

Fix @tailwindcss/vite Rolldown Resolver Crash

Fix @tailwindcss/vite crashing with 'Missing field tsconfigPaths' under Vite 8's Rolldown resolver. Upgrade Vite and Rolldown to clear it.

Aug 5, 2026Read more →

Vite's own migration guide text stating format sniffing between package.json browser and module fields has been removed, next to an explicit resolve.mainFields config

Guides & Fixes

Fix Vite 8 Browser/Module Field Resolution Change

Fix Vite 8 removing format sniffing between package.json browser and module fields. Explicit resolve.mainFields order now matters.

Aug 5, 2026Read more →

A code comparison showing build.rollupOptions renamed to build.rolldownOptions in a Vite config, with the same manualChunks function unchanged

Guides & Fixes

Fix Vite 8's build.rollupOptions Deprecation

Fix the build.rollupOptions deprecation warning in Vite 8. Rename to build.rolldownOptions before the old key is removed.

Aug 5, 2026Read more →

A code comparison showing Vite's own migration guide text on CommonJS default import interop, alongside the legacy.inconsistentCjsInterop config flag that restores the old behavior

Guides & Fixes

Fix Vite 8 CommonJS Default Import Breaking Change

Fix Vite 8 breaking CommonJS default imports under Rolldown's stricter interop. Restore the old behavior with one legacy config flag.

Aug 5, 2026Read more →

Vite's own migration guide text stating require calls for externalized modules are now preserved as require calls, next to a Node.js createRequire interop fix

Guides & Fixes

Fix Vite 8 Externalized require() Behavior Change

Fix Vite 8 no longer converting require() of externals into import statements. ESM-only output can now throw at runtime.

Aug 5, 2026Read more →

A code comparison showing a CSS rule with both backdrop-filter and -webkit-backdrop-filter before minification, and only -webkit-backdrop-filter surviving after Vite 8's default Lightning CSS minification

Guides & Fixes

Fix Vite 8 Lightning CSS Dropping backdrop-filter

Fix Vite 8's Lightning CSS minifier silently dropping unprefixed backdrop-filter in production builds. One cssMinify config line restores it.

Aug 5, 2026Read more →

A terminal window showing the real error: Invalid output options for manualChunks, Expected Function but received Object, from a Vite 8 build using the old object-form vendor chunk config

Guides & Fixes

Fix Vite 8 manualChunks Object Form Removed

Fix Vite 8 rejecting object-form manualChunks. Rolldown only supports the function form - here's the real error and the fix.

Aug 5, 2026Read more →

Vite's own migration guide text stating the Oxc transformer does not support lowering native decorators, next to a tsconfig.json experimentalDecorators setting

Guides & Fixes

Fix Vite 8 Oxc Not Lowering Native Decorators

Fix Vite 8's Oxc transformer not lowering native class decorators. Understand the limitation and the real workaround for older build targets.

Aug 5, 2026Read more →

A code comparison showing resolve.alias customResolver, removed in Vite 8, replaced by a plugin using a resolveId hook with enforce: 'pre'

Guides & Fixes

Fix Vite 8 resolve.alias customResolver Removal

Fix Vite 8 removing resolve.alias customResolver, which breaks CSS/JS path-alias plugins. Astro's own core fix shows the replacement.

Aug 5, 2026Read more →

The same strong and span markup rendered under two Astro versions: Astro 6 shows 'Save 20%' with the space intact, Astro 7 shows 'Save20%' with the space collapsed by the new compressHTML default

Guides & Fixes

Fix Astro 7 compressHTML Spacing Bug After Upgrade

Astro 7 changes compressHTML's default, collapsing space between inline elements on separate lines. Here's why, and the two ways to fix it.

Aug 4, 2026Read more →

A terminal window showing Astro's real InvalidContentEntryDataError output for an invalid category value, with the exact field and reason it prints

Guides & Fixes

Fix Astro InvalidContentEntryDataError Schema Errors

InvalidContentEntryDataError means a post's frontmatter doesn't match its schema. Here's how to read the message and fix the four most common causes.

Aug 4, 2026Read more →

A terminal window showing the wrangler.toml assets configuration with not_found_handling set to 404-page, the setting that makes Cloudflare Workers serve a real custom 404 page

Guides & Fixes

Fix Cloudflare Workers Empty 404 Page on Static Sites

Cloudflare Workers Static Assets doesn't serve your custom 404.html by default. Here's the exact config that fixes it, confirmed on a live production site.

Aug 4, 2026Read more →

A terminal window showing a real npm ERESOLVE error after upgrading to Astro 7: npm cannot resolve vite@8.2.0 against a plugin's peer dependency capped at Vite 7

Guides & Fixes

Fix ERESOLVE Vite 8 Peer Dependency Errors in Astro 7

Fix the ERESOLVE peer dependency error when npm install fails after upgrading to Astro 7, caused by plugins that don't yet support Vite 8.

Aug 4, 2026Read more →

Side-by-side code comparison: broken Astro markup with {count} and {label} on separate lines rendering as '5posts', next to the fixed version with an explicit {" "} rendering correctly as '5 posts'

Guides & Fixes

Why Astro Silently Merges Text Like '5posts' Into One Word

Astro silently collapses whitespace between two expressions on separate lines, merging {count} and {label} into '5posts'. Here's the one-character fix.

Jul 30, 2026Read more →

Diagram of a details/summary dropdown menu with an X marking a click outside it, and an arrow showing the dropdown closing in response

Guides & Fixes

Fixing <details> Dropdowns That Won't Close on Outside Click

Native <details>/<summary> dropdowns only toggle via their own <summary>. Click anywhere else and it stays open. Here's the small, dependency-free fix.

Jul 30, 2026Read more →

Close-up of colorful syntax-highlighted code on a screen, representing debugging structured data

Guides & Fixes

Fixing 'Missing Field Author' in Google's Rich Results Test

Why Google's Rich Results Test flags a missing author field on Article pages, and how to add correct Person and Organization JSON-LD in Astro to resolve it.

Jul 27, 2026Read more →