An Ultimate Guide to Debugging JWTs in Your Web App

Turkay Kalenci — Wed, 12 Nov 2025 17:34:06 +0000

As developers, we are often forced to treat JSON Web Tokens (JWTs) as "magic black boxes." We get them from the auth server, stick them in a "Bearer" header, and pray.

The moment we see {"error": "Invalid Token"}, we panic.

Is it expired? Is the signature wrong? Is the server down? This guide will turn that black box into a clear glass box. This is a systematic process for debugging any JWT problem.

ANATOMY OF A JWT (THE 30-SECOND REFRESHER)
A JWT is just three strings, separated by dots: xxxx.yyyyy.zzzz

HEADER: Contains the algorithm (e.g., HS256).

PAYLOAD: Contains the data (e.g., userId, iat (Issued At), exp (Expiration Time)).

SIGNATURE: Ensures the token wasn't tampered with.

The Header and Payload are just Base64-encoded JSON. They are not encrypted. They are public.

THE DEBUGGING FLOWCHART: A STEP-BY-STEP GUIDE
Stop guessing. Follow this process.

STEP 1: IS IT BEING SENT? Before anything else, open your browser's Network tab.

Find your failed API request (it will be red, usually a 401 or 403 status).

Click on it. Go to the "Headers" tab.

Look at "Request Headers." Do you see Authorization: Bearer [long string]?

If not, your front-end code is failing to attach the token. Your token isn't "invalid," it's "missing."

STEP 2: IS IT MALFORMED? (THE MANUAL DECODE) If the token is being sent, copy that long string (without the "Bearer" part). Now, you need to see what's inside. Manually copying the middle part (the Payload) and pasting it into a generic Base64 decoder is slow and clunky.

This is why a dedicated JWT Debugger is essential. For my own workflow, I use a simple online tool (like the one at toolunify.com/en/encoder-decoder/jwt-debugger/) which instantly decodes the Header and Payload JSON for me.

Check the decoded payload. Is the JSON valid? Does it have the userId or sub (Subject) claim you expect?

STEP 3: IS IT EXPIRED? In that decoded payload, find the exp claim. It will look like this: 1678886400. This is a Unix timestamp. Go to a Unix Time converter (like the one in the toolunify.com suite) and check that date. If that time is in the past, your token is expired. Your front-end code needs to use its "refresh token" to get a new one.

STEP 4: IS THE SIGNATURE VALID? If the token is sent, is not malformed, and is not expired, then the only remaining option is a failed signature. This is a backend problem. This means the server (which has the "secret key") tried to verify the token and failed. This usually happens in two cases:

The token was tampered with on the client-side.

The server's secret key is wrong (e.g., dev and prod keys don't match).

CONCLUSION: STOP TREATING AUTH AS MAGIC
By following this flowchart, you've systematically ruled out every possibility.

Check Network Tab (Is it sent?)

Check Payload (Is it malformed?)

Check exp claim (Is it expired?)

If all else fails, blame the backend (Invalid Signature).

Stop guessing, and start debugging.

The Base64 Dilemma: When (and How) to Actually Inline Images in CSS

Turkay Kalenci — Wed, 12 Nov 2025 17:33:38 +0000

We’ve all heard the advice: "Inline your small images into CSS using Base64! It saves an HTTP request!" It sounds like a clear performance win.

I took this advice to heart on a recent project. I dutifully converted all my small SVG icons into Base64 strings and embedded them directly into my main stylesheet.

Then I ran Lighthouse. My performance score had tanked.

My "optimized" CSS file had ballooned to over 1.5MB, completely blocking the page render. This was the "lived experience" that forced me to learn the real trade-offs of Base64 inlining.

This isn't just "what is Base64." This is the practical guide I wish I had found on Google when I was trying to figure out what went wrong.

THE REAL-WORLD TRADE-OFFS
We need to compare four critical metrics: HTTP Requests, File Size, Rendering, and Caching.

HTTP REQUESTS This is the obvious one. Base64 wins. By inlining the image, you save a network request for each asset. Fewer requests are good. But at what cost?

FILE SIZE This is the first trap. Base64 encoding is not efficient. It takes binary data (the image) and converts it into text, which increases the file size by roughly 33%. That 2KB icon? It's now about 2.7KB inside your CSS file. This adds up fast.

RENDERING (THE HIDDEN KILLER) This is what destroyed my Lighthouse score. A browser must download and parse a CSS file before it can paint the page (it's "render-blocking").

SCENARIO A (External): style.css (100KB) + 5 small icons (2KB each, 10KB total). The 100KB CSS loads fast. The icons load asynchronously. The page renders quickly.

SCENARIO B (Inlined): style.css (100KB + 13.5KB from 5 inlined icons) = 113.5KB. Now imagine 50 icons. My CSS file became a 1.5MB monster that held the entire page hostage. A fast-loading page with a few async icons is almost always better than a page that waits for one giant, slow-loading CSS file.

CACHING This is the final nail in the coffin. When an icon is an external file (icon.svg), the browser caches it. If you change your CSS, the icon stays cached. When you inline that icon into your CSS, it becomes part of the CSS file. If you change any line of that CSS (like a color or font size), the entire 1.5MB file must be re-downloaded by the user, including all 50 inlined icons.

THE "TRICK": MY NEW BEST PRACTICE
After that disaster, I developed a simple 3-question checklist.

Is the image tiny (e.g., under 2KB)?

Is the image critical for the initial page load (e.g., a "loading" spinner or an "X" icon for a modal that must be visible immediately)?

Will this image rarely change?

If the answer to all three is "Yes," then I'll consider inlining it.

For everything else? Use modern formats (like .webp or .avif) and let the browser's powerful caching system do its job.

MY PRACTICAL WORKFLOW
For my build process, I use CLI tools (like openssl base64) to automate this.

But for quick debugging or testing, I need to grab a string fast. This was one of the frustrations that led me to build my own utility suite. I just use a simple, no-ads online encoder (like the one I built for my own workflow at toolunify.com/en/encoder-decoder/base64/) to grab the string, test it in my CSS, and check the performance impact.

Base64 is a sharp tool, not a blunt hammer. Use it surgically.

DEV Community: Turkay Kalenci

An Ultimate Guide to Debugging JWTs in Your Web App

The Base64 Dilemma: When (and How) to Actually Inline Images in CSS