# Truquence for n8n FAQ: Contracts, PASS, FAIL, UNKNOWN > Plain answers about Truquence for n8n: why a green run can be wrong, what a contract is, which files to export and what PASS, FAIL and UNKNOWN mean. Source: https://learn.ynteractive.com/content/blog/truquence-n8n-check-faq · Updated 2026-10-21 · Free from Stepthrough (https://learn.ynteractive.com) Quick answer Truquence is a free, open-source command-line tool that checks whether an n8n run got the right answer, not just whether it ran. You give it an exported [n8n execution](https://learn.ynteractive.com/content/glossary/execution) and a contract that says what each node should have produced. It reads both offline and answers **PASS**, **FAIL** or **UNKNOWN**, and a FAIL names the node. The free [Truquence n8n lesson](https://learn.ynteractive.com/content/truquence-n8n-workflow-success-but-wrong-output) walks through it in about 11 minutes with the exact commands from Truquence's own docs. Last updated October 21, 2026 [Take the free module →](https://learn.ynteractive.com/courses/n8n-jump-start/22)Module 22 of the free [n8n Jump Start](https://learn.ynteractive.com/courses/n8n-jump-start) course, about 11 minutes. No account needed. By [Robert Breen](https://learn.ynteractive.com/content/about) · Published October 21, 2026 · Updated October 21, 2026 · 5 min read Truquence · n8n · Testing · FAQ The example is made up. Priya Nair runs Cedar Row Accounting. Her [n8n workflow](https://learn.ynteractive.com/content/glossary/workflow) builds about 40 client [invoices](https://learn.ynteractive.com/content/glossary/invoice) a month. Last month one run said **status: success**, every node green, but the **Total** node passed along 12.0 where the invoice should say 120.0. Truquence has no app screens, so the practice is a plain terminal. The commands and output lines come from Truquence's README and docs/workflows.md, read on 20 October 2026, and the FAIL output is the excerpt the docs print for their own synthetic run. This is our own lesson, not an official Truquence course. ## Why can an n8n run say success and still be wrong? Because in n8n, success means every node finished without an error. n8n cannot know what the right answer was. A wrong total, a missing row or a swapped name all look green, and the client is the one who finds it. So many owners spot-check every result by hand. In the lesson, Priya spends 4 minutes on each of about 40 invoices, over 2.5 hours a month (example numbers, so swap in your own). Skip the check, and an invoice goes out for $12.00 instead of $120.00. ## How does the Truquence check work, step by step? The lesson follows five parts: 1. **Install it.** Clone the code with **git clone https://github.com/cplj/truquence-public.git**, then **cd truquence-public**. Install it in its own Python environment with **python3 -m venv .venv && . .venv/bin/activate && python3 -m pip install .** 2. **Export two files from n8n.** **workflow.json** is the exported workflow. **execution.json** is the full export of the run, with every node's output. 3. **Make the contract.** Run **truquence init --workflow workflow.json --out contract.json**. It adds one check for every enabled node, each starting as **x-expect_items: null**. 4. **Write what right looks like.** Replace **null** on the Total check with **[{"total": 120.0}]**, worked out from the client's timesheet, and do the same for every node. 5. **Run the check.** Run **truquence accept --format n8n --contract contract.json --execution execution.json --out run** and read the result. Each [n8n execution](https://learn.ynteractive.com/content/glossary/n8n-execution) is one run of the workflow, and the export is plain [JSON](https://learn.ynteractive.com/content/glossary/json), so Truquence can read it without touching your n8n. ## Try it free, step by step **Truquence: Catch an n8n Run That Says Success but Gets It Wrong**. A business case for a small firm whose n8n invoice run said success while the total was wrong: write down what each node should output, check the exported run with Truquence offline, and read PASS… You do every step yourself in a practice copy of Truquence, it checks your work as you go, and “Do it for me” finishes any step you get stuck on. Free, and nothing touches your real accounts. [Start the free lesson](https://learn.ynteractive.com/modules/truquence-n8n-acceptance) [Or read the full step-by-step guide](https://learn.ynteractive.com/content/truquence-n8n-workflow-success-but-wrong-output) ## What does a FAIL look like? In the lesson, the check returns **FAIL** with exit code **1**. Two checks passed and one failed: **Total**, because the "Exact JSON output items differ from expected (including item count and order)." n8n said success; Truquence says the invoice is wrong and names the node. It also writes **run.json** and **run.md**. After the fix and a fresh export, the check returns **PASS** with exit code **0**. ## Key takeaways - Green in n8n means the run finished, not that the answer is right. - The contract is your answer key: write it from the source, never from the run you are checking. - Export the full execution, not just the workflow. - Only **PASS** lets the work go on. **FAIL** and **UNKNOWN** both block it. - A person still signs off: Truquence checks the run, it does not approve the business result. ## Frequently asked questions **Is Truquence free?** Yes. It is open source under the Apache-2.0 license, on GitHub at [github.com/cplj/truquence-public](https://github.com/cplj/truquence-public). It runs on your own computer with no account. **What do I need to install it?** From the README: Git, Python 3.10 or newer with venv and pip, and a POSIX shell, such as the Terminal on a Mac or Linux. **What if the install says externally-managed-environment?** Activate **.venv** and run the install again there. The same fix applies if you see *command not found*. **Does Truquence change my n8n workflow?** No. Nothing is installed in your n8n. It reads only the files you give it, offline, and no input causes a network call or a workflow run. It does not run, fix or approve your workflow. **Which n8n export does Truquence need?** The full execution export: one JSON object with **finished**, the **workflowData** snapshot and every node's output under **data.resultData.runData**. A workflow-only export, a copy of the console or a partial export comes back UNKNOWN. The docs' [local n8n walkthrough](https://github.com/cplj/truquence-public/blob/main/docs/local-n8n.md) shows one way to export a full run. **What is in the contract file?** Each check names a node, how many times it should run (**x-expect_runs**) and the items it should output (**x-expect_items**). Run counts, item counts, values and order must match exactly. An empty list **[]** means the node should output nothing. **What is the x-workflow_sha256 line?** A fingerprint of the workflow's settings, so a changed workflow cannot pass against an old contract. **Where should the expected output come from?** From the source, worked out by you. In the lesson, 8 hours at $15 is 120.0, from the timesheet. Truquence's docs say never to copy it from the run you are checking, or a wrong run will pass. Think of it as [test data](https://learn.ynteractive.com/content/glossary/test-data) with a known right answer. **What do the exit codes mean?** **0** is PASS. **1** is FAIL: the run contradicts the contract. **2** is UNKNOWN: not enough to decide, for example an expectation still null, an unfinished run or a missing snapshot. **3** means Truquence could not write the report. **Can I run the check again with the same report name?** Truquence never overwrites an earlier report, so use a new name such as **--out run-2** next time. **Does it work on every n8n workflow?** The n8n adapter covers JSON-only, single-branch nodes. Workflows with untaken branches or binary items come back UNKNOWN and need a person to review. **Where can I learn more?** Read [Truquence n8n check mistakes](https://learn.ynteractive.com/content/blog/truquence-n8n-check-mistakes) and [how to test an n8n workflow](https://learn.ynteractive.com/content/blog/how-to-test-an-n8n-workflow), then [try the practice](https://learn.ynteractive.com/modules/truquence-n8n-acceptance). ## Free lessons in this post - [Truquence: Catch an n8n Run That Says Success but Gets It Wrong](https://learn.ynteractive.com/content/truquence-n8n-workflow-success-but-wrong-output): A business case for a small firm whose n8n invoice run said success while the total was wrong: write down what each node should output, check the exported run with… ## Watch it in a free lesson: Find and Use n8n Templates ### Find and Use n8n Templates: video walkthrough Full walkthrough · 3:32 · with captions Skip the blank canvas. Find a ready-made workflow in the n8n template gallery, import it into your workspace, connect Google Sheets and Gmail, test it with a real form entry and publish it. The whole lesson narrated step by step, recorded in Stepthrough’s simulated practice environment. [Watch it with chapters and the full transcript](https://learn.ynteractive.com/content/find-and-use-n8n-templates#watch) From the free lesson [Find and Use n8n Templates](https://learn.ynteractive.com/content/find-and-use-n8n-templates) ## Related terms Plain-English definitions, each with an example from a free lesson. [Execution](https://learn.ynteractive.com/content/glossary/execution) · [Workflow](https://learn.ynteractive.com/content/glossary/workflow) · [Invoice](https://learn.ynteractive.com/content/glossary/invoice) · [Acceptance testing](https://learn.ynteractive.com/content/glossary/acceptance-testing) · [Golden dataset](https://learn.ynteractive.com/content/glossary/golden-dataset) · [Edge case](https://learn.ynteractive.com/content/glossary/edge-case) · [LLM observability](https://learn.ynteractive.com/content/glossary/llm-observability) · [Regression testing](https://learn.ynteractive.com/content/glossary/regression-testing) [The full AI glossary](https://learn.ynteractive.com/content/glossary) ## Keep reading - [Truquence for n8n: 8 Acceptance Check Mistakes](https://learn.ynteractive.com/content/blog/truquence-n8n-check-mistakes): Truquence mistakes that let a wrong n8n run through: copying the answer from the run, a partial export, treating UNKNOWN as fine and reusing old contracts. - [n8n Showing Feedback Agent FAQ: Real Estate Setup](https://learn.ynteractive.com/content/blog/n8n-showing-feedback-agent-faq): Plain answers about an n8n AI agent that turns buyer agents' showing feedback into one row per showing in Google Sheets for the weekly seller update. - [n8n Law Firm Time Entry Agent FAQ: Setup and Rules](https://learn.ynteractive.com/content/blog/n8n-law-time-entry-agent-faq): Plain answers about an n8n AI agent that turns a lawyer's rough notes into time entries in Google Sheets, with hours exactly as written. [All blog posts](https://learn.ynteractive.com/content/blog) · [All free tutorials](https://learn.ynteractive.com/content)