The example is made up. Priya Nair runs Cedar Row Accounting. Her n8n workflow builds about 40 client invoices 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:
- 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 .
- 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.
- 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.
- 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.
- Run the check. Run truquence accept --format n8n --contract contract.json --execution execution.json --out run and read the result.
Each n8n execution is one run of the workflow, and the export is plain 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 lessonWhat 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. 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 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 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 and how to test an n8n workflow, then try the practice.
