DEV Community

Amit Verma
Amit Verma

Posted on Originally published at tayloramitverma.com on

7 Silent Bugs I Found Redesigning My Next.js Portfolio (and How I Fixed Them)

None of these bugs threw an error. Each one shipped, passed the build, and quietly made the site worse. Here's what they were, why they happened, and the one-line-ish fix for each.

I recently redesigned this site — new hero, new colour system, new header and footer — on Next.js 16, Tailwind CSS and Payload CMS. The visual work was the easy part. The interesting part was what I found underneath: seven bugs that had been live for months, none of which produced an error message.

That's the common thread. A crash gets fixed the same day. A bug that silently degrades the experience can survive for a year. If you run a Next.js site, at least one of these is probably on yours.

1. The sticky header that wasn't sticky

The header had position: sticky; top: 0. In the browser, it scrolled away with the page like any other element.

The cause was two lines in the global CSS, added long ago to stop horizontal scrolling on mobile:

html,
body {
  width: 100%;
  overflow-x: hidden;
}
Enter fullscreen mode Exit fullscreen mode

When both html and body have a non-visible overflow, the html value is applied to the viewport — but body becomes a scroll container of its own. A sticky element sticks relative to its nearest scroll container. The header was now sticking inside <body>, which never scrolls (the window does), so it never stuck.

The fix is overflow-x: clip. It still prevents sideways scrolling, but clip doesn't create a scroll container:

html,
body {
  width: 100%;
  overflow-x: clip;
}
Enter fullscreen mode Exit fullscreen mode

How to check yours: scroll down and run getComputedStyle(document.body).overflowY in the console. If it isn't visible, sticky descendants may be affected.

2. The font that never loaded

The layout loaded Nunito Sans with next/font, exactly as the docs show — but every heading on the live site rendered in the system font. Nothing in the console.

const nunito = Nunito_Sans({ subsets: ['latin'], variable: '--font-nunito-sans' })

// The variable class was on <body>…
<html lang="en">
  <body className={nunito.variable}>
Enter fullscreen mode Exit fullscreen mode

Two things were wrong. First, nothing in the Tailwind config used --font-nunito-sans, so the font downloaded and was never applied. Second — and this is the trap — the obvious fix makes things worse. Tailwind's base styles put font-family on html. If you point fontFamily.sans at var(--font-nunito-sans) while the variable is defined on body, the variable is undefined on html, the whole declaration becomes invalid, and the page falls back to the browser default: Times New Roman.

The fix has two parts — define the variable on <html>, and give var() a fallback so any layout that doesn't load the font still gets the system stack:

<html lang="en" className={nunito.variable}>

// tailwind.config.mjs
fontFamily: {
  sans: ['var(--font-nunito-sans, ui-sans-serif)', ...defaultTheme.fontFamily.sans],
},
Enter fullscreen mode Exit fullscreen mode

3. A hydration mismatch only dark-mode visitors saw

I added a light/dark toggle to the header. In light mode, fine. In dark mode, React logged: "A tree hydrated but some attributes of the server rendered HTML didn't match the client properties."

The component chose its icon and aria-label from the current theme:

const { theme } = useTheme()
const isDark = theme === 'dark'
return <button aria-label={isDark ? 'Switch to light theme' : 'Switch to dark theme'}>…</button>
Enter fullscreen mode Exit fullscreen mode

The server can't know a visitor's theme — it lives in localStorage — so the server rendered the light version, and dark-mode browsers hydrated the dark version. Different attributes, mismatch.

The fix is to make the rendered markup theme-independent and let CSS do the switching. With Tailwind's darkMode: ['selector', '[data-theme="dark"]'], the dark: variant follows the attribute on <html>:

export function ThemeToggle() {
  const { setTheme } = useTheme()
  const toggle = () => {
    const current = document.documentElement.getAttribute('data-theme')
    setTheme(current === 'dark' ? 'light' : 'dark')
  }
  return (
    <button type="button" onClick={toggle} aria-label="Toggle light and dark theme">
      <Sun className="scale-0 dark:scale-100" />
      <Moon className="absolute scale-100 dark:scale-0" />
    </button>
  )
}
Enter fullscreen mode Exit fullscreen mode

The click handler reads the theme at click time, so nothing theme-dependent is rendered on the server.

4. "Not Found" from Gemini through the Vercel AI SDK

My portfolio's AI assistant can run on Claude, Groq or Gemini. Groq and Gemini are reached through their OpenAI-compatible endpoints with @ai-sdk/openai. After an upgrade, every Gemini request failed with AI_APICallError: Not Found.

The cause: recent versions of the AI SDK's OpenAI provider route provider(modelId) to OpenAI's newer Responses API (/responses). The OpenAI-compatible endpoints from Gemini and Groq only implement Chat Completions. So the SDK was calling a URL that doesn't exist there.

const gemini = createOpenAI({
  baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai',
  apiKey: process.env.GEMINI_API_KEY,
})

// ❌ uses the Responses API → 404 on OpenAI-compatible providers
const model = gemini('gemini-2.5-flash')

// ✅ explicitly use Chat Completions
const model = gemini.chat('gemini-2.5-flash')
Enter fullscreen mode Exit fullscreen mode

Lesson: "OpenAI-compatible" usually means compatible with Chat Completions, not with everything OpenAI ships.

5. The chat that answered with nothing

Even before that fix, the symptom was strange: the chat endpoint returned HTTP 200 with an empty body. No error in the UI — just an empty reply bubble.

With streamText, the response starts streaming as soon as you return it. If the model call fails afterwards — bad API key, quota, outage — the 200 status has already been sent and can't change. The error was swallowed.

Two small changes make this visible. On the server, log errors that happen mid-stream:

const result = streamText({
  model,
  system,
  messages,
  onError: ({ error }) => {
    console.error('[portfolio-chat] model error:', error)
  },
})
return result.toTextStreamResponse()
Enter fullscreen mode Exit fullscreen mode

On the client, treat an empty stream as a failure instead of rendering a blank message:

if (!assistantText.trim()) {
  setLastMessage("Sorry, I couldn't generate an answer just now. Please try again.")
}
Enter fullscreen mode Exit fullscreen mode

And while you're there: don't return internal error strings like GEMINI_API_KEY is not configured to the browser. Log them, and send visitors a generic "temporarily unavailable" message.

6. An image sizes attribute the browser ignored

Every image on the site had this sizes value, generated by a helper from the original template:

sizes="(max-width: 1920px) 3840w, (max-width: 1536px) 3072w, (max-width: 1280px) 2560w"
Enter fullscreen mode Exit fullscreen mode

sizes must contain lengths — 100vw, 400px, 50vw — describing how wide the image will be displayed. The w unit belongs in srcset, not here. Browsers treat the whole value as invalid and fall back to 100vw, so a 400px card downloads an image sized for the full viewport.

The fix is to default to a valid value and pass real sizes from the components that know their layout:

const sizes = sizeFromProps ?? '100vw'

// a card in a 3-column grid:
<Media resource={cover} size="(min-width: 1024px) 368px, (min-width: 640px) 50vw, 100vw" />
Enter fullscreen mode Exit fullscreen mode

7. A scroll-spy that never highlighted anything

The header nav was supposed to highlight the section you're reading. It never did. The hook looked for links starting with #:

const sectionIds = hrefs.filter((href) => href.startsWith('#')).map((href) => href.slice(1))
Enter fullscreen mode Exit fullscreen mode

But the CMS stored the nav links as absolute URLs — https://www.tayloramitverma.com/#about — so the filter matched nothing. A small normaliser fixed both the highlight and the smooth-scroll click handler, which had the same blind spot:

export function toSectionHash(href: string): string {
  if (href.startsWith('#')) return href
  const match = href.match(/^(?:https?:\/\/(?:www\.)?tayloramitverma\.com)?\/?(#[^/?]+)$/i)
  return match ? match[1] : href
}
Enter fullscreen mode Exit fullscreen mode

Three quick ones

  • A Tailwind class that doesn't exist. I wrote h-4.5 w-4.5 for an icon. Tailwind v3's default scale has 3.5 but not 4.5, so no CSS was generated and the icon silently rendered at its 24px default. Use h-[18px] or extend the spacing scale.
  • A mobile menu under the chat buttons. The drawer had z-50; the floating chat and WhatsApp buttons had z-[100], so they sat on top of the open menu. Write your z-index layers down in one place.
  • A closed drawer you could still tab into. An off-canvas menu hidden with translate-x-full is still focusable. Add inert when it's closed so keyboard and screen-reader users don't land on invisible links.

How I caught them

None of these showed up in the build, and only one showed up in the console. What found them was looking at the real thing:

  • Screenshots at several widths and both themes , compared side by side.
  • Measuring instead of eyeballing — checking getBoundingClientRect().top of the header after scrolling, naturalWidth of images, scrollWidth vs clientWidth for overflow.
  • Calling the API directly with curl instead of trusting the UI, which is how the empty 200 response showed up.
  • Reading computed styles , not source styles. The source said sticky; the behaviour said otherwise.

If you take one thing from this post: when something "should work" but doesn't, measure what the browser actually did. The bug is usually in the gap between what the code says and what the page does.

Related posts


Originally published at www.tayloramitverma.com.

Top comments (0)