The example is made up. Priya Nair runs Cedar Row Accounting, and her n8n workflow builds about 40 client invoices a month. Last month one run said status: success while the Total node output 12.0 instead of 120.0. Truquence is a free, open-source command-line tool with no app screens, so the lesson is a plain terminal with the exact commands and output excerpts from Truquence's README and docs/workflows.md, read on 20 October 2026.
What are the most common Truquence mistakes?
| # | Mistake | Fix |
|---|---|---|
| 1 | Copying expected output from the run under review | Work it out from the source, such as the timesheet |
| 2 | Trusting n8n's green success | Check every node's output against a contract |
| 3 | Exporting only the workflow, or part of the run | Export the full execution as execution.json |
| 4 | Leaving an expectation as null | Replace every null with the items that node should output |
| 5 | Treating UNKNOWN as a pass | Only PASS (exit 0) lets the work go on |
| 6 | Reusing the old contract after changing the workflow | Run truquence init again and re-enter your expected items |
| 7 | Installing outside a virtual environment | Activate .venv and install there |
| 8 | Expecting Truquence to approve the business result | A person still signs off |
Why must I write the answer key myself?
1. Copying from the run. The contract is your answer key: for each node, how many times it runs and exactly what it outputs. Truquence's docs are firm that you write the expected output yourself and never copy it from the run you are checking. In the lesson, 8 hours at $15 is 120.0, worked out from the timesheet. Copy 12.0 from the run, and the wrong invoice passes.
2. Trusting green. In n8n, success means every node finished without an error. It does not know what the right answer was. A wrong total, a missing row or a swapped name all look green. That is why Priya was spot-checking about 40 invoices by hand at 4 minutes each, over 2.5 hours a month (example numbers).
Why does Truquence return UNKNOWN?
3. The wrong export. Truquence needs two files. workflow.json is the exported workflow, one workflow object, not a list. execution.json is 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.
4. A null left behind. truquence init --workflow workflow.json --out contract.json adds one check for every enabled node, each starting as x-expect_items: null, meaning not decided yet. A null stays UNKNOWN. Replace each one. If a node should output nothing, write an empty list []. Run counts, item counts, values and order must match exactly.
An unfinished run or a missing snapshot also returns UNKNOWN. So do workflows outside what the n8n adapter covers: it handles JSON-only, single-branch nodes, and untaken branches or binary items need a person to review.
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 lessonWhy should UNKNOWN stop the invoice?
5. Reading UNKNOWN as "didn't fail". Truquence has three answers. PASS is exit code 0. FAIL is exit code 1, as in the lesson, where two checks passed and Total failed because the "Exact JSON output items differ from expected." UNKNOWN is exit code 2: not enough to decide. FAIL and UNKNOWN both block acceptance. Treating UNKNOWN as fine is how a half-checked invoice gets sent. If you script the check, let only exit code 0 move the work on.
What changes when I fix the workflow?
6. Reusing the old contract. Fix the Total node in n8n, run the workflow again and export the new execution. If you changed the workflow itself, its fingerprint, the x-workflow_sha256 line, changes too, so a changed workflow cannot pass against an old contract. Run truquence init again and re-enter your expected items. Never just paste in the new fingerprint. With the right total, the check returns PASS.
Also give each check a new report name. Truquence writes run.json and run.md and never overwrites an earlier report, so use --out run-2 the second time.
What setup and scope mistakes should I avoid?
7. Installing in the wrong place. The README asks for Git, Python 3.10 or newer with venv and pip, and a POSIX shell. Install with python3 -m venv .venv && . .venv/bin/activate && python3 -m pip install . If you see externally-managed-environment or command not found, activate .venv and run the install again there.
8. Expecting a sign-off. Truquence does not run, fix or approve your workflow. The report's business_acceptance is always UNKNOWN: Truquence checks the run against your contract, and a person still signs off. That is human in the loop at the last step.
Key takeaways
- Write each expected output from the source, never from the run you are checking.
- Export the full execution, and replace every null in the contract.
- Only PASS lets the work go on; UNKNOWN blocks it like FAIL.
- Make a new contract after changing the workflow, and a new report name each run.
- Truquence checks the run; a person still approves the result.
Frequently asked questions
- Does Truquence need an account or internet access?
No. It is open source under Apache-2.0 at github.com/cplj/truquence-public, runs on your own computer with no account, and reads the files offline.
- Will a FAIL tell me which node is wrong?
Yes. In the lesson the FAIL line names Total and gives the reason.
- Can I just paste the new fingerprint into my contract?
No. Truquence's docs say a changed workflow needs a newly reviewed contract, so run init again and re-enter your expected items.
- What is a good first workflow to check?
The one your business would least like to get wrong, with a result you can work out by hand, such as an invoice total. See the n8n execution entry for what one run contains.
- Where can I read more answers?
See the Truquence n8n check FAQ, how to test an n8n workflow and the lesson guide.
