November 5, 2026 · 8 min read

Debugging Shopify Functions: Run Logs, Input Queries, and app function replay

Master Shopify Functions debugging using function run logs, input query scope rules, and app function replay to reproduce live failures locally.

Debugging Shopify Functions: Run Logs, Input Queries, and app function replay

Shopify Functions expose three distinct debugging surfaces: streamed terminal logs from app dev, structured JSON files in .shopify/logs/, and function run logs in the Dev Dashboard. Knowing which surface to reach for at which stage of development cuts debugging time from hours to minutes. The app function replay command closes the loop by letting you re-run a real production execution locally, against your live code, without touching the merchant's store again.

Key takeaways

  • shopify app dev streams function logs to your terminal and writes per-execution JSON files to .shopify/logs/.
  • app function replay --log <six-char-id> re-executes a captured input locally, so you can iterate without re-triggering the function on Shopify.
  • Dev Dashboard run log visibility is controlled by your app's access scopes, not by manual merchant sharing (changed May 13, 2026).
  • Function logs are truncated at 1 kB in the Dev Dashboard; design your log statements accordingly.
  • The instruction budget is 11 million Wasm instructions per execution (for carts up to 200 line items), not wall-clock time. The Dev Dashboard shows the instruction count per run.

The three debugging surfaces and when to use each

I keep a mental map with three layers, moving from innermost (local) to outermost (production):

SurfaceWhen to useKey limitation
app dev terminal + .shopify/logs/Active development against a dev storeOnly fires when the browser triggers the function; can't replay arbitrary inputs
app function run --input fixture.jsonUnit-level testing against a known or mocked inputInput must be hand-crafted or copied from a log; not wired to a live session
app function replay --log <id>Reproducing a real execution (dev or production input) locallyRequires a captured log file; production runs need Dev Dashboard export
Dev Dashboard function run logsPost-deploy debugging, merchant-reported failuresScope-gated (see below); logs truncated at 1 kB

In practice I move top-to-bottom: build fast locally with fixtures, then graduate to replay once the function is wired to a dev store, then drop into the Dev Dashboard for anything that escapes to production.

app dev: what actually gets written to disk

When you run shopify app dev, the CLI streams execution logs to your terminal and writes a separate JSON file to .shopify/logs/ for every function execution that fires on your dev store. Each file is named <timestamp>_<namespace>_<handle>_<id>.json and contains the full input, output, instruction count, and any STDERR/log output your function emitted.

The six-character <id> suffix is what app function replay calls the "log file identifier." That identifier is also printed inline in the app dev terminal output next to each execution. Copy it, and you have a stable handle to that exact execution forever.

If your app has more than one Function extension, you can filter the stream. In a second terminal:

shopify app logs --source extensions.my-discount-function

Run shopify app logs sources first to get the exact handle names for your extensions.

CLI 5.0 note: Shopify CLI 5.0 removed the standalone app logs and app logs sources commands. The migration guide says to use app dev output instead for Function logs. If you are on CLI 4.x these commands still work; check shopify version before assuming either path.

app function replay: the fastest feedback loop

app function replay re-executes the compiled Wasm binary in your current directory using the input from a previously logged execution. It watches for file changes and re-runs automatically, giving you a tight edit-compile-test loop without needing a browser open.

# Replay using a specific log ID (copy from app dev output)
shopify app function replay --log a3f9c1

# If you don't have the ID, pick interactively from recent executions
shopify app function replay

There is also a --json flag (added in a recent CLI PR) that streams structured JSONL output, which is useful if you want to pipe the execution result into jq or a test harness:

shopify app function replay --log a3f9c1 --json --no-input | jq '.result.instructions'

The replay output includes instructions, memory_usage, input, output, and success. That instructions field is the one to watch when you are approaching the 11 million instruction budget.

Where do replay inputs come from?

You can feed app function replay (and app function run) from four places:

  • Log files from app dev (.shopify/logs/*.json)
  • Output of app logs on CLI 4.x
  • Function run logs copied from the Dev Dashboard
  • A hand-crafted mock JSON that matches your input query schema

Option 3 is the most valuable for production bugs: you export the exact input Shopify sent to the failing execution, drop it locally, and replay it. No guessing what the merchant's cart looked like.

Dev Dashboard run logs and the scope gate (May 2026 change)

Before May 13, 2026, getting run log details for a production store required the merchant to manually share the log from the Discounts tab. That friction is gone. As of that changelog update, function run log details in the Dev Dashboard are automatically visible to your app whenever the app holds the access scopes required by the function's input query.

The mechanic is straightforward: Shopify derives the required scopes from the fields your input query reads. If your query touches customer.email, your app needs read_customers. If it touches cart.lines[].product.metafields, it needs read_products. Miss any scope and the Dev Dashboard shows the run metadata (timestamp, shop, success/failure) but hides the input and output payload entirely.

Practical checklist when logs are blank:

  • Open your function's input.graphql (or .graphql input query file).
  • List every field the query reads.
  • Cross-reference each field against the Shopify access scopes reference.
  • Add any missing scopes to your shopify.app.toml.
  • For scopes only needed during debugging (not normal app operation), declare them as optional scopes. Merchants can grant or revoke optional scopes without reinstalling the app.

One gotcha: customer data fields (email, addresses, order history) fall under protected customer data scopes, which require a separate approval from Shopify. Plan for that review time before your next production debugging session.

Writing log statements that survive the 1 kB truncation

The Dev Dashboard truncates function logs after 1 kB per execution. That is roughly 1,000 characters. At that limit, one verbose JSON.stringify(input) call burns your entire budget before you see anything useful.

In JavaScript:

// Bad: burns the entire 1 kB on one object
console.error(JSON.stringify(input));

// Better: log only the values your conditional logic branches on
console.error(`subtotal=${input.cart.cost.subtotalAmount.amount} lines=${input.cart.lines.length} tag=${input.cart.buyerIdentity?.customer?.tags?.join(',')}`);

In Rust, write to the Shopify logging API (shopify_function::logging::log) rather than eprintln!. Both end up in the STDERR section of the Dev Dashboard under "Logs," but the Shopify macro is the idiomatic path and less likely to change.

Design your log statements to answer the specific question you are debugging: which branch did the function take, what was the key input value, what did the output operations array contain? Three targeted lines beat a wall of JSON every time.

Reading the instruction count before it bites you

Every function run log in the Dev Dashboard and every app function replay JSON output includes the instruction count for that execution. The hard ceiling is 11 million Wasm instructions for carts up to 200 line items, with the budget scaling proportionally above that threshold.

Two rules I apply to every function in a catalog with 10,000+ SKUs:

  • Alert threshold: If the instruction count exceeds roughly 8.8 million (80% of the budget) on any observed run, the function is at risk on a large-cart order. Add a monitoring check on the Dev Dashboard logs.
  • Language trade-off: Shopify's own docs note that JavaScript functions burn through the instruction budget significantly faster than equivalent Rust functions on the same logic. For the same quantity-limit validation, Rust uses about 19,000 instructions versus roughly 183,000 in JavaScript on a simple example. At scale, that ratio compounds. If you are seeing instruction-count creep on a JavaScript function with large carts, compile profiling via app function replay --json and inspect the instructions field across several cart sizes before rewriting.

The app function build command compiles your function to Wasm without deploying it. Run it, then run app function run --input fixture.json against the compiled binary to get an instruction count in a fully offline loop, before app dev even enters the picture.

Common failure patterns and what to check first

  • Function ran, output is empty, no error logged: Check whether your input query returns the fields your conditional logic reads. A field absent from the query returns null at runtime; the function silently exits the branch and returns no operations. Use app function replay to inspect the exact input payload and verify field presence.
  • Dev Dashboard shows a run but no details: The app is missing at least one scope required by the input query. See the scope checklist above.
  • Local app function run returns correct output but the dev store does not apply the result: The compiled Wasm binary the CLI runs locally may be stale. Run shopify app function build explicitly before running app function run.
  • app dev app-logs panel shows "Error while polling app logs, retrying in 5 seconds": A known intermittent issue on CLI 4.7.x and 4.8.x. The function still runs and writes log files to .shopify/logs/; use app function replay against those files rather than depending on the streaming panel.
  • InvalidInputQueryError in the Dev Dashboard: Your input query references a field that does not exist in the API version your function's shopify.extension.toml declares. Run shopify app function typegen to regenerate types against the current schema, then compare.

Putting the workflow together

Here is the sequence I run when a function misbehaves:

  1. shopify app function build to get a fresh .wasm binary.
  2. shopify app dev against a dev store; trigger the relevant checkout flow once.
  3. Copy the six-character log ID from the terminal output.
  4. shopify app function replay --log <id> in watch mode; edit the function; the CLI recompiles and re-runs on each save.
  5. When the local output looks correct, check the Dev Dashboard for instruction count and log output from the dev store run.
  6. For a production failure: export the input from the Dev Dashboard run, save it as fixtures/prod-failure.json, and repeat from step 4 using --input fixtures/prod-failure.json with app function run.

This loop eliminates the most expensive debugging anti-pattern: deploying a change to production, waiting for a merchant to trigger the checkout flow again, and squinting at a 1 kB log snippet to work out what happened.

For a worked example of a function that silently returns nothing and how to trace the root cause through replay, see the case studies section of this blog.

Teams without in-house Shopify developers can bring this to Lintel, my Shopify engineering studio, for Shopify Functions development.

Frequently asked questions

Why can't I see function run log details in the Dev Dashboard even though the function ran?

The Dev Dashboard gates log details on the access scopes your app holds. Shopify derives the required scopes from every field your function's input query reads. If any required scope is missing, you see the run metadata but the input and output payloads are hidden. Add the missing scopes to your shopify.app.toml and re-request them from the merchant.

What is the difference between app function run and app function replay?

app function run executes your compiled Wasm binary against a JSON input you supply manually or via a fixture file. app function replay fetches the input from a previously logged real execution (identified by its six-character log ID) and re-runs the function against it, then watches for code changes and re-runs automatically. Replay is faster for debugging real failures because you don't have to construct the input yourself.

How do I debug a Shopify Function that works locally but fails on the dev store?

The most common cause is a stale compiled binary. Run shopify app function build explicitly to recompile, then re-test with app function run. If the output still differs, compare the exact input your local fixture uses against the input logged by app dev in .shopify/logs: a field your conditional logic depends on may be absent from the input query and therefore null at runtime on the live store.

Seven years of Shopify, on one page.

Roles, projects, stack and certifications are on the resume.

Resume Download PDF LinkedIn