Debugging Your App

The first question: where does this code run?

Beginners lose hours looking for logs in the wrong place. Your app's code runs in three different places, and each prints its output somewhere different.

DevTools inside the Shopify admin

Your app is an iframe inside the admin, which changes how you use the browser's developer tools.

The console

By default the console shows the Shopify admin's page, not yours. At the top of the Console tab is a context dropdown, usually reading top. Switch it to your app's frame to see your own logs and run commands in your page.

The network tab

This shows every request your page makes — the most useful debugging view there is. React Router's data requests end in .data, so filter for that:

.data

Click a request to see what was sent and, crucially, what came back. A status of 401, 404 or 500 tells you immediately which layer failed, and the response body often contains the real error message.

A method that always works

1. Reproduce it reliably

   Find the exact steps that cause the problem every time. A bug you cannot trigger on demand, you cannot confirm you fixed.

2. Find which layer broke

   Browser, your server, the database, or Shopify? The network tab and the table above usually answer this in a minute.

3. Read the actual error

   The whole message, not the first few words. In a stack trace, find the first line that points at your file rather than a library.

4. Check your assumptions with real values

   Log what the code actually receives. The bug is almost always a value that is not what you assumed — a string instead of a number, undefined, a different shape.

5. Change one thing, then test

   Several changes at once means you will not know which one fixed it — or which one broke something else.

6. Confirm the original steps now work

   Repeat step 1 exactly. Then check you did not break anything nearby.

Before anything else: is this the code that is running?

A surprising share of "impossible" bugs are this. You are reading one version of the code, and a different one is running.

• Right branch? git branch --show-current
• Right config? shopify app info — dev app, or production?
• Database client current? npx prisma generate after switching branches.
• Server restarted after editing .env?
• In production: was the container rebuilt (--build), or is it still the old image?
• Settings change? Was shopify app deploy actually run?
• Browser serving a cached page? Hard-refresh.

Thirty seconds on this list saves hours of debugging code that is not even running.

Logging that actually helps

// Useless — prints [object Object]
console.log("data: " + data);

// Useful — the whole structure, readable
console.log("[products loader] data:", JSON.stringify(data, null, 2));

• Prefix every log with where it came from — [products loader]. With several logs flying past, you need to know which is which.
• Log the whole object with JSON.stringify(x, null, 2), not string concatenation.
• Log the full Shopify response when an API call misbehaves — the answer is usually in userErrors or a top-level errors array you were not reading.
• Remove noisy debug logs before committing. Keep a few meaningful ones, such as job failures.

Your debugging tools

"It works on my machine"

Your dev setup is kinder than production in three ways, and each hides a class of bug:

So test the way production behaves: a second dev store, demo data, a large image, and your browser's network throttling set to a slow connection.

Debugging in production

You cannot open the merchant's browser console, so:

• Start with your server logs. Most production errors are server-side, and they are already recorded.
• Ask for specifics. The exact steps, the time it happened, a screenshot of any error.
• Reproduce on a dev store with similar data — often the difference is the size or shape of their catalogue.
• Record errors where you can find them — a lastError column for jobs, logged failures with the shop name. You cannot debug what nobody wrote down.

Error lookup table

The messages you are most likely to meet, and where the explanation is.

When you are truly stuck

• Explain the problem out loud, step by step, to a colleague or even to nobody. You will often spot the wrong assumption mid-sentence.
• Make the smallest version that still fails. Strip away everything unrelated until the bug has nowhere to hide.
• Take a break. Genuinely. Fresh eyes find in five minutes what tired ones missed for an hour.
• When you ask for help, include: what you expected, what happened instead, the exact error, and what you have already tried.

Cheat sheet

# where are my logs?
loader / action / jobs   → terminal (dev) · docker compose logs (prod)
components               → browser console — switch context to your frame
webhooks / extensions    → shopify app logs · Dev Dashboard

# first checks
network tab, filter ".data"      no request = browser · error = server
is this the code running?        branch · config · prisma generate · rebuild

# log well
console.log("[where]", JSON.stringify(x, null, 2))
never log tokens, secrets or personal data

# method
reproduce → find the layer → read the whole error
→ check real values → change one thing → confirm