DEV Community: cobra

When proofs fail on Midnight: Debugging proof server errors and ZK generation failures

cobra — Mon, 15 Jun 2026 14:24:59 +0000

This guide shows how to diagnose and fix four common proof-generation failures on Midnight: a proof server that is not responding, a slow first proof or client timeout, proof rejection caused by a wire format mismatch, and version mismatches between the proof server and the ledger stack. Each command and log example in this guide was tested in a local environment.

Use this guide when your Midnight DApp cannot reach the proof server, proof generation times out, /check or /prove rejects a request, or proof generation starts failing after a version change.

What this guide covers

Proof server liveness and version verification
Proof server not responding
Slow first proof or timeout
Wire format mismatch on proof server requests
Version mismatch between the proof server and the local ledger stack

Tested environment

Note: The examples below use focused local reproductions rather than a single DApp flow. The timeout reproduction uses a local helper script, k16-direct-prove-timeout.mjs, with the compiled transferOwnership circuit from OpenZeppelin’s test-only MockZOwnablePK.compact. The helper generates a valid serialized preimage before calling /prove. The script and compiled artifacts are not included with this article, so the commands show the exact tested invocation but are not copy-paste-ready on their own. The version-mismatch section uses a local Hello World DApp flow. The wire-format section uses saved /check payloads so request encoding can be tested in isolation. Use the same diagnostic pattern in your own Midnight DApp.

Item	Value
Verified as of	April 16, 2026
OS	macOS 15.6
CPU	arm64
Docker	29.1.2
Node.js	22.21.1
npm	10.9.4
Compact	0.5.1
Compact compile	0.30.0
Proof server image	`midnightntwrk/proof-server:8.0.3`

Prerequisites

Before you start, make sure you have:

Docker Desktop running
Node.js installed
Compact installed
A local Midnight project or DApp flow that triggers proof generation
Terminal access
The proof server image version that matches your local stack

Start from a healthy proof server

Start with one known-good proof server. Do this before changing versions, editing payloads, or tuning timeouts.

Run the standalone proof server on port 6300:

docker run --rm --name midnight-proof-server-319-k16-cold -p 6300:6300 midnightntwrk/proof-server:8.0.3 -- midnight-proof-server -v

In another terminal, use /version as the proof server liveness and version check. The proof server does not expose a dedicated /health route, so a successful /version response confirms that the service is reachable and reports the running version:

curl -i http://localhost:6300/version

A healthy proof server returns HTTP/1.1 200 OK and the version string:

HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8

8.0.3

You can also inspect the container and recent logs:

docker ps --filter "name=midnight-proof-server"
docker logs --tail 20 midnight-proof-server-319-k16-cold

A healthy startup eventually shows the server listening on 0.0.0.0:6300:

starting service: "actix-web-service-0.0.0.0:6300", workers: 10, listening on: 0.0.0.0:6300

Fix a proof server that is not responding

Symptom

The standalone proof server on the default local endpoint is not responding. Start by checking the proof server container state, preserved logs, and the /version liveness check on port 6300. For this test, the endpoint was http://localhost:6300/version.

What to check

Check four things:

Is the proof server container running?
Do the startup logs show a healthy startup state?
Does http://localhost:6300/version respond?
After stopping the container, does Docker show that the container exited while /version stops responding?

Commands

For this test, I used a named standalone container without --rm so Docker state and logs would still be available after the container was stopped.

Start the proof server:

docker run -d --name midnight-proof-server-319-a -p 6300:6300 midnightntwrk/proof-server:8.0.3 -- midnight-proof-server -v

Then verify the healthy state:

docker ps --filter "name=midnight-proof-server-319-a"
docker logs midnight-proof-server-319-a
curl -i http://localhost:6300/version

In this test, docker ps showed the container running on 0.0.0.0:6300->6300/tcp, the startup logs included Actix runtime found; starting in Actix runtime and listening on: 0.0.0.0:6300, and the /version check returned HTTP/1.1 200 OK with body 8.0.3. That established a known-good baseline before reproducing the failure.

Now stop that same standalone container and diagnose the result with Docker-based checks:

docker stop midnight-proof-server-319-a
docker ps -a --filter "name=midnight-proof-server-319-a"
docker inspect midnight-proof-server-319-a
docker logs midnight-proof-server-319-a
curl -i http://localhost:6300/version

What the logs show

This test produced a real non-responding state, and the strongest evidence came from Docker rather than from curl alone:

docker ps -a showed the container had exited.
docker inspect showed "Status": "exited" and "Running": false.
docker logs were still preserved because the container had been created without --rm.
The /version endpoint no longer responded on http://localhost:6300/version.

The preserved logs are also useful because they show what happened at shutdown. They do not show a crash or an application exception. Instead, they show a clean stop sequence beginning with SIGTERM received; starting graceful shutdown, followed by worker shutdown lines and accept thread stopped. After that, curl -i http://localhost:6300/version failed with curl: (7) Failed to connect to localhost port 6300.

Root cause

The most conservative, evidence-backed root cause is that the standalone container process had stopped, so nothing was listening on port 6300.

Fix

Because this test used a named container without --rm, the exact tested recovery command was:

docker start midnight-proof-server-319-a

Verify the fix

After restarting the same container, verify /version again:

curl -i http://localhost:6300/version

In this test, that final check returned HTTP/1.1 200 OK with body 8.0.3, confirming that the proof server was reachable again on the standard local endpoint.

Diagnose a slow first proof or timeout

Symptom

The first proof request is slow or fails with an abort-style timeout. On a cold proof server, the server may need to download or initialize ZK parameter and key material before the proof can finish. In this test, the logs showed cold parameter and key downloads, a real /prove timeout, and success after increasing the timeout.

What to check

Check three things:

Did the proof flow reach /prove?
Did the proof server start cold and fetch missing parameter or key material?
Does the same proof succeed with a higher timeout?

Commands

The commands below are the exact commands used in the tested reproduction. They depend on the local helper script and compiled circuit assets described above, so treat them as illustrative unless you have equivalent local assets.

Start from a cold proof server and watch its logs:

docker logs --tail 80 midnight-proof-server-319-k16-cold

Run the direct proof path with a low timeout:

K16_PROVE_TIMEOUT_MS=1000 node k16-direct-prove-timeout.mjs

Then run the same direct proof path with a higher timeout:

K16_PROVE_TIMEOUT_MS=300000 node k16-direct-prove-timeout.mjs

What the logs show

The cold proof server fetched missing public parameters and key material:

Ensuring zswap key material is available...
Missing public parameters for k=10. Attempting to download from the host ...
Missing public parameters for k=11. Attempting to download from the host ...
Missing public parameters for k=12. Attempting to download from the host ...
Missing zero-knowledge proving key for Zswap inputs. Attempting to download from the host ...
Missing zero-knowledge proving key for Dust spends. Attempting to download from the host ...

The low-timeout proof attempt reached the proof path and then aborted:

PREIMAGE_OK
serializedPreimage.length=323
publicTranscript.length=36
privateTranscriptOutputs.length=2
PROVE_ATTEMPT_START
proofServer=http://localhost:6300
circuitId=transferOwnership
timeoutMs=1000
PROVE_ERROR
error.name=AbortError
error.message=The user aborted a request.

The proof server also showed the /prove request:

POST /prove HTTP/1.1; took 5.111326s

The higher-timeout run succeeded:

PROVE_ATTEMPT_START
proofServer=http://localhost:6300
circuitId=transferOwnership
timeoutMs=300000
PROVE_OK
proof.length=4508

Root cause

The client timeout was too low for the first proof path. The proof server was alive, but the client aborted before proof generation finished.

Fix

Increase the proof provider timeout for first-run proof generation. Keep the timeout high enough for cold parameter and key initialization.

Verify the fix

Run the same proof path again with the higher timeout:

K16_PROVE_TIMEOUT_MS=300000 node k16-direct-prove-timeout.mjs

The proof succeeds when the timeout is high enough:

PROVE_OK
proof.length=4508

Do not treat every timeout as a DUST or wallet problem. In this test, the valid timeout evidence used a direct /prove path and avoided an earlier wallet/deploy path that failed before proof generation with insufficient DUST.

Fix proof rejection caused by a wire format mismatch

Symptom

The proof server rejects a request even though the server is running. This can happen when the request body does not match the serialized wire format expected by /check or /prove.

What to check

Check whether your client sends the exact serialized payload expected by the proof server. Do not hand-edit, truncate, stringify, or re-encode the binary request body.

The examples below use ./evidence as the evidence folder. Replace it with your own folder if you store test files somewhere else.

Commands

Send a known-good /check payload:

curl -sS \
  -D ./evidence/05-good-check.headers.txt \
  -o ./evidence/05-good-check.body.bin \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @./evidence/05-wire-format-good-check.bin \
  http://127.0.0.1:6300/check

Then send a truncated copy of that payload:

curl -sS \
  -D ./evidence/05-bad-check.headers.txt \
  -o ./evidence/05-bad-check.body.bin \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @./evidence/05-wire-format-bad-check-truncated.bin \
  http://127.0.0.1:6300/check

What the logs show

The good payload returned 200 OK:

GOOD_HEADERS
HTTP/1.1 200 OK
content-length: 30

The truncated payload returned 400 Bad Request:

BAD_HEADERS
HTTP/1.1 400 Bad Request
content-length: 27

BAD_BODY_PREVIEW
failed to fill whole buffer

The proof server logged the parse failure:

Error in response: Error { kind: UnexpectedEof, message: "failed to fill whole buffer" }
POST /check HTTP/1.1; took 0.001360s

Root cause

The request body no longer matched the expected wire format because the payload was truncated.

Fix

Send the original binary payload generated by the Midnight tooling. Keep the content type as application/octet-stream, and use --data-binary when testing with curl.

Verify the fix

Resend the unmodified payload:

curl -sS \
  -D ./evidence/05-fix-good-check.headers.txt \
  -o ./evidence/05-fix-good-check.body.bin \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @./evidence/05-wire-format-good-check.bin \
  http://127.0.0.1:6300/check

The fixed request returns 200 OK:

FIX_GOOD_HEADERS
HTTP/1.1 200 OK
content-length: 30

Fix a version mismatch between the proof server and the ledger stack

Symptom

Your local stack is reachable, but proof generation fails after you change the proof server image or a ledger-related package.

What to check

Compare the proof server Docker tag with the ledger and runtime packages used by your local DApp.

Commands

Inspect the local package versions and proof server image:

npm list @midnight-ntwrk/ledger-v8
npm list @midnight-ntwrk/compact-runtime
npm list @midnight-ntwrk/onchain-runtime-v3
docker ps | grep proof-server
docker inspect --format='{{.Config.Image}}' example-hello-world-proof-server-1

A known-good local stack used @midnight-ntwrk/ledger-v8@8.0.3 with this proof server image:

midnightntwrk/proof-server:8.0.3

To reproduce a mismatch, I changed the proof server image to an older major version:

image: 'midnightntwrk/proof-server:7.0.0'

Then I ran the same local test flow again.

What the logs show

The mismatched proof server accepted traffic, but proof generation failed:

× Hello World Contract > Deploys the contract 301111ms
  → Failed to prove transaction

(FiberFailure) Wallet.Proving: Failed to prove transaction

The proof server logs showed that the failing run reached /prove:

GET /version HTTP/1.1; took 0.008403s
Starting to process request for /prove...

Root cause

The proof server image did not match the local ledger stack. The server was reachable, but the proof path was not compatible with the versions used by the DApp and wallet stack.

Fix

Restore the proof server image to the version that matches the local ledger packages:

image: 'midnightntwrk/proof-server:8.0.3'

Restart the local stack with the same startup command used by your project.

Verify the fix

Run the same local test flow again. The aligned stack should pass:

✓ Hello World Contract > Deploys the contract
✓ Hello World Contract > Stores Hello World!

Test Files  1 passed (1)
Tests       2 passed (2)

One important note: an older patch tag did not fail in this setup. Do not assume every older proof server tag reproduces a mismatch. Use the supported version set for your stack and verify with a real proof-generating flow.

Proof server liveness checklist

Use this checklist before changing DApp code:

docker ps shows the proof server container running.
curl -i http://localhost:6300/version returns HTTP/1.1 200 OK.
The response body includes the proof server version, for example 8.0.3.
docker logs shows the service listening on 0.0.0.0:6300.
Cold startup logs may show missing public parameters or zero-knowledge proving keys being downloaded and verified.
A low timeout can fail even when the proof server is healthy.
A Docker health status can be misleading if the container health check depends on a tool that is missing inside the container.
The proof server Docker tag matches the ledger version used by the local stack.
/check and /prove requests use the correct binary wire format.

Wrap up

When proof generation fails, start with the /version liveness check, then inspect Docker logs, and then identify the exact failure boundary. A connection failure, an abort timeout, a rejected binary payload, and a version mismatch can look similar from a DApp, but they leave different signals in the proof server logs.

Decoding error 1010 on Midnight: What "Invalid Transaction" actually means

cobra — Mon, 15 Jun 2026 14:16:35 +0000

What this guide covers

1010: Invalid Transaction often leaves Midnight developers with an error that is too generic to fix on its own. In most cases, 1010 is the outer JSON-RPC / author-RPC error, not the full diagnosis. The more useful clue is often in error.data, such as Custom error: 186.

The sections below explain the 1010 error structure, how to read Custom error: N, how to interpret custom codes 139, 154, 168, 170, and 186, and how Midnight’s five-dimensional ledger cost model relates to block-limit diagnosis.

Scope and evidence basis

This is a source-backed diagnostic tutorial. It focuses on decoding 1010: Invalid Transaction, interpreting Custom error: N, mapping custom codes 139, 154, 168, 170, and 186, and explaining how Midnight’s five-dimensional ledger cost model affects block-limit diagnosis.

The mappings and worked examples here are based on public Midnight source code, documentation, forum discussions, and issue threads linked throughout the guide and in the Sources checked section. None of the five custom-code failure paths was reproduced first-hand by the author. Any local command output used during research was limited to basic tooling capture, not end-to-end reproduction of these failures.

Verification date and version scope

Verification date: May 10, 2026
Sources and version scope reverified: June 15, 2026
Runtime mapping source: midnight-node commit 948b7dbcd975ce5a360d83f6353c2b4872482621
Issue #667 reported versions: Compact compiler 0.29.0 / 0.30.0-rc.0, compact-js 2.5.0, and ledger-v8 8.0.0
Issue #731 reported versions: Midnight.js packages 4.0.2, ledger-v8 8.0.3, compact-js 2.5.0, Compact runtime 0.15.0, compactc 0.30.0, proof server 8.0.3, and the preview network after the March 25, 2026 reset

The numeric mappings in this guide are version-specific. Verify them against the midnight-node and ledger versions used by your application.

Prerequisites

Start by capturing the full error returned by your wallet, toolkit, DApp, or JSON-RPC client. The most useful fields are error.code, error.message, and error.data.

If you are debugging a local setup, also record your package versions, target network, node status, and indexer status if the transaction produced a hash. Include proof server status only if the failing flow depends on proof generation. Do not start by changing smart contract code from the number 1010 alone.

Error 1010 is not the whole diagnosis

1010: Invalid Transaction is best treated as a two-layer error.

The outer layer is the JSON-RPC / author-RPC invalid transaction error. It tells you that the transaction was rejected as invalid by the submission path, but it is usually not specific enough to explain why.

The inner layer is the diagnostic detail, which often appears in error.data. Depending on the failure, error.data may contain a built-in invalid transaction reason or a Midnight runtime custom code such as:

{
  "code": 1010,
  "message": "Invalid Transaction",
  "data": "Custom error: 186"
}

In this case, 1010 tells you the transaction was rejected as invalid. Custom error: 186 tells you where to investigate next.

This distinction matters because the same outer error can point to very different underlying problems, including block-limit pressure, malformed transaction effects, or fee-calculation and builder-side issues.

How the 1010 error structure works

The outer invalid-transaction code comes from the upstream author-RPC error mapping. In the shorthand often used for this error family, AUTHOR(1000) refers to the author-RPC error family whose base value is 1000; POOL_INVALID_TX adds 10 to that base, producing 1010.

BASE_ERROR = 1000
POOL_INVALID_TX = BASE_ERROR + 10
1000 + 10 = 1010

So 1010 is the outer invalid-transaction wrapper. It is not a Midnight-specific custom code by itself.

The custom part, when present, appears inside error.data as decimal text:

Custom error: N

That N is the value to map against Midnight’s runtime custom-code mapping. For example:

Custom error: 186

should be investigated as code 186, not as generic 1010.

Also note that not every 1010 has to be a Custom error: N case. Some failures can appear as built-in invalid transaction reasons. For block-limit diagnosis, this matters because a transaction may be rejected through a block-exhaustion path and still appear under the outer 1010 invalid-transaction error.

How to find the inner custom code

When you see 1010: Invalid Transaction, do this before changing code:

Capture the full JSON-RPC error.
Record error.code.
Record error.message.
Record error.data.
Check whether error.data contains a built-in invalid transaction reason or Custom error: N.
If it contains Custom error: N, map N using the code table below.
Check wallet, toolkit, builder, node, or indexer logs where they are relevant to the failure. Include proof server logs only if the failing flow depends on proof generation.
Reduce the failing action to the smallest transaction, circuit call, or deployment that still fails.
Re-run after the targeted fix and compare before-and-after evidence.

The main rule is simple: do not diagnose from 1010 alone. Diagnose from the inner detail.

Worked example: reading the useful part of the error

Suppose your client shows this error:

{
  "code": 1010,
  "message": "Invalid Transaction",
  "data": "Custom error: 186"
}

Read it in two passes:

code: 1010 means the transaction was rejected as invalid by the submission path.
data: "Custom error: 186" is the part to investigate next.

Using the code map below, treat 186 as an effects-check failure, so the next question is not “why did JSON-RPC return 1010?” It is whether the transaction’s declared effects match the effects the ledger computes during validation.

Code map: 139, 154, 168, 170, and 186

This guide focuses on five custom codes that are especially useful when diagnosing 1010: Invalid Transaction: 139, 154, 168, 170, and 186.

The source-defined mappings below are verified against the midnight-node runtime custom-code mapping at commit 948b7dbcd975ce5a360d83f6353c2b4872482621. The table separates the exact runtime mapping from the practical area to investigate. These mappings are version-specific, so check the source for the exact Midnight version you are running.

Code	Source-defined runtime mapping	First thing to suspect	Practical diagnostic area
139	`MalformedError::UnknownError`	the number alone is not specific enough	inspect wallet, toolkit, builder, and fee-calculation logs
154	`LedgerApiError::BlockLimitExceededError`	transaction or deployment pressure against block limits	check transaction size, deployment size, and cost-model pressure
168	`MalformedError::FeeCalculation`	fee calculation or transaction assembly	inspect fee calculation, balancing, transcript partitioning, settlement, and transaction-assembly logs
170	`MalformedError::InvalidDustSpendProof`	an invalid or stale DUST spend proof	inspect DUST proof validity, Merkle-root freshness, and witness freshness
186	`MalformedError::EffectsCheckFailure`	declared effects do not match ledger-computed effects	inspect the mismatch between declared and computed transaction effects

Evidence and reproduction status

The runtime mappings below are verified from the pinned midnight-node source. “Not reproduced” means the author did not personally trigger and capture that error in a local or network transaction.

Code	Evidence basis	First-hand reproduction
139	Pinned runtime source and Midnight.js issue #667	No. All five mappings are source-backed; none was reproduced first-hand by author.
154	Pinned runtime source and public block-limit documentation and discussion
168	Pinned runtime source; practical guidance based on the source-defined `FeeCalculation` mapping
170	Pinned runtime source; practical guidance based on the source-defined `InvalidDustSpendProof` mapping
186	Pinned runtime source, Midnight.js issue #731, and its validation repository

Quick diagnostic matrix

Use this table for a first-pass triage after you identify the inner custom code.

If you see	First place to look	Why
`Custom error: 139`	wallet/toolkit/builder logs	the number alone may not identify the final root cause
`Custom error: 154`	transaction size, deployment size, cost pressure	the transaction may be pushing against block limits
`Custom error: 168`	batch settlement, fee calculation, balancing	this often points to a settlement-adjacent transaction assembly path
`Custom error: 170`	Merkle-root freshness, DUST spend proof, witness freshness	stale or pruned root assumptions can surface through the proof/witness path
`Custom error: 186`	declared vs ledger-computed effects	the transaction effects may not match what ledger validation computes

The matrix above is the fast triage view. The sections below explain each code in more detail.

Code 139

What you may see:

A transaction submission fails under outer 1010, with the inner detail showing Custom error: 139. In practice, developers may first encounter this during transaction construction in builder, wallet, or toolkit flows.

What it usually means in practice:

At the pinned runtime version, code 139 maps to MalformedError::UnknownError. Treat it as a non-specific malformed-transaction signal rather than a final diagnosis. The useful place to look is the surrounding wallet, toolkit, and builder logs.

In Midnight.js issue #667, an unshielded NIGHT operation surfaced through RPC as 1010: Invalid Transaction: Custom error: 139, while the more detailed toolkit output identified a fee-calculation rejection. This example shows why you should use 139 as a starting point and inspect the surrounding toolchain logs for the more specific failure.

First place to check:

Start with wallet, toolkit, builder, and transaction-construction diagnostics. The RPC code may be less specific than the logs produced by the surrounding toolchain.

Diagnostic steps:

Capture the full JSON-RPC error and confirm whether error.data contains Custom error: 139.
Check toolkit, wallet, and builder logs for a more specific malformed-transaction or fee-related diagnostic.
Review the transaction-construction path that assembled the failing extrinsic.
Reduce the failing action to the smallest transaction or circuit call that still produces the same inner code.

What not to assume:

Do not assume that 139 by itself proves one exact root cause. Do not present “transaction builder” as the verified public enum name. The safer move is to treat 139 as a malformed-transaction signal and use the surrounding toolkit or builder logs for the more useful clue.

Code 154

What you may see:

A transaction fails under outer 1010 with a block-limit-style symptom. It may appear as custom 154, or it may appear as a built-in invalid transaction reason such as block exhaustion.

What it usually means in practice:

At the pinned runtime version, code 154 maps to LedgerApiError::BlockLimitExceededError. Treat it as a block-limit signal. The transaction, deployment, or state update may be pushing against one or more ledger cost dimensions.

The useful next step is to inspect transaction size, deployment size, smart contract complexity, and cost-model pressure before assuming the smart contract logic itself is broken.

First place to check:

Start with transaction size, deployment size, smart contract complexity, and Midnight’s five-dimensional ledger cost model: readTime, computeTime, blockUsage, bytesWritten, and bytesChurned.

Diagnostic steps:

Capture the full error and check whether the inner detail is Custom error: 154 or a built-in block-exhaustion reason.
Inspect whether the failing action is a large deployment, state-heavy update, or complex transaction.
Check which cost-model dimension is most likely under pressure: reads, compute, block usage, bytes written, or bytes churned.
Reduce transaction or deployment complexity, then re-run and compare the new error output.

What not to assume:

Do not assume every block-limit failure appears as custom 154. Some block-limit failures may still be wrapped by outer 1010 while surfacing through a built-in invalid transaction path.

Code 168

What you may see:

A transaction fails under outer 1010 while the wallet, toolkit, or DApp is assembling a transaction that needs settlement, balancing, or fee calculation. Developers may see this described as a batch-settlement-style failure because the transaction fails while the final transaction package is being assembled or reconciled.

What it usually means in practice:

At the pinned runtime version, code 168 maps to MalformedError::FeeCalculation. In practice, inspect the settlement and transaction-assembly path: fee calculation, balancing, transcript partitioning, and how the final transaction package is assembled.

This is especially relevant when the failing transaction touches NIGHT movement paths such as sendUnshielded or receiveUnshielded, because the transaction may fail before the problem looks like a bug in the smart contract.

First place to check:

Start with the batch-settlement or transaction-assembly path: fee calculation, balancing behavior, transcript partitioning, and wallet or toolkit diagnostics around how the final transaction was assembled.

Diagnostic steps:

Capture the full error and confirm whether the inner detail is Custom error: 168.
Inspect wallet and toolkit logs for settlement, balancing, transcript, or fee-calculation details.
Review how the final transaction package is assembled, especially where unshielded receive or send paths are involved.
Reduce the action to the smallest transaction that still exercises the same settlement, balancing, or fee-calculation path.

What not to assume:

Do not assume that 168 proves one exact settlement mechanism or a Compact circuit bug. The safer debugging move is to inspect the batch-settlement, fee-calculation, balancing, and transaction-assembly path before changing smart contract code.

Code 170

What you may see:

A transaction fails under outer 1010, with the inner detail showing Custom error: 170. The pinned runtime source maps code 170 to MalformedError::InvalidDustSpendProof. Stale or mismatched proof, witness, or state-root data are possible diagnostic areas, not additional source-defined meanings of the code.

What it usually means in practice:

At the pinned runtime version, code 170 maps to MalformedError::InvalidDustSpendProof. Treat it as a DUST spend proof failure whose investigation may include Merkle-root and witness freshness. The useful place to look is whether the proof, witness, or state root used to assemble the transaction is stale, mismatched, pruned, or no longer matches the state expected during validation.

First place to check:

Start with Merkle-root freshness, DUST spend proof validity, stale proof assumptions, and whether the proof or witness binding still matches the transaction being submitted.

Diagnostic steps:

Capture the full error and confirm whether error.data contains Custom error: 170.
Check whether the failing transaction includes a DUST spend proof, witness, or state-root-dependent path.
Review whether the proof, witness, Merkle root, and transaction data are stale, pruned, mismatched, or assembled from different states.
Rebuild the transaction from fresh state where possible, then rerun and compare the before-and-after error data.

What not to assume:

Do not assume that 170 proves one exact pruning trigger or one exact stale-root mechanism. The safer diagnostic area is Merkle-root freshness plus the DUST spend proof path: proof validity, witness freshness, and whether the proof still matches the transaction being submitted.

Code 186

What you may see:

A transaction fails under outer 1010, with the inner detail showing Custom error: 186.

What it usually means in practice:

At the pinned runtime version, code 186 maps to MalformedError::EffectsCheckFailure. Midnight.js issue #731 documents a 1010: Invalid Transaction: Custom error: 186 case involving a circuit that combined mintShieldedToken with receiveUnshielded. The transaction was assembled with one set of effects, but the ledger validation path rejected the resulting effects check.

That means the next debugging step is not the proof server, and not the outer 1010 wrapper. The next step is to inspect how the final transaction effects were assembled.

First place to check:

Start with the transaction effects. The key question is whether the effects declared by the assembled transaction match the effects computed by the ledger during validation.

Diagnostic steps:

Capture the full error and confirm whether error.data contains Custom error: 186.
Inspect the transaction assembly path for combined actions that may alter the final declared effects.
Compare the intended effects with the effects the ledger would compute from the final transaction.
Reduce the failing action to the smallest transaction that still produces the effects-check failure.

What not to assume:

Do not treat 186 as a generic proof-server problem. The useful diagnostic area is effects mismatch: compare the transaction’s declared effects against the effects the ledger computes during validation.

Block-limit-related failures need one more piece of context: Midnight’s five-dimensional ledger cost model.

The five-dimensional ledger cost model

Midnight’s block-limit diagnosis should be understood through its five-dimensional ledger cost model:

readTime
computeTime
blockUsage
bytesWritten
bytesChurned

The practical model is:

transaction cost = (readTime, computeTime, blockUsage, bytesWritten, bytesChurned)

Each dimension is normalized against its corresponding block limit. The dimension with the highest normalized value becomes the main source of pressure. If any dimension exceeds its limit, the transaction can be rejected.

This matters because a transaction does not need to be “too big” in every way to fail. One dimension can dominate. For example, a deployment might be acceptable in read pressure and compute pressure but fail because bytesWritten exceeds the allowed limit. Another transaction might have moderate byte size but fail because validation or execution pressure is too high.

Be careful with exact numbers. Unless you have current network-specific parameters, do not claim exact block-limit thresholds or exact units for every dimension. For diagnostics, the safe lesson is that block-limit failures are measured across five dimensions, and the largest normalized dimension is the one to investigate first.

Diagnostic workflow

Use this order when investigating 1010: Invalid Transaction:

Capture the full error object.
Separate the outer 1010 wrapper from the inner detail.
Look for error.data.
Decide whether error.data is a built-in invalid transaction reason or Custom error: N.
If you have Custom error: N, map N to the code table.
Record package versions, tooling versions, and target network.
Check toolkit, wallet, builder, node, and indexer logs where relevant. Include proof server logs only if the failing flow depends on proof generation.
Reduce the failing action to the smallest transaction, circuit call, or deployment that still fails.
Apply a targeted fix based on the mapped failure family.
Re-run and compare the before-and-after evidence.

The most important habit is to preserve the full error before changing anything. A screenshot or copied line that only says 1010 is usually not enough.

Evidence to capture before asking for help

Before posting in a forum, Discord, or GitHub issue, capture:

full JSON-RPC error
error.code
error.message
error.data
custom code, if present
package versions
network used
transaction hash, if available
wallet/toolkit logs
node logs, if relevant
proof server status, only if the failing flow depends on proof generation
indexer status, if relevant
smallest failing smart contract, circuit, deployment, or action

This evidence helps others distinguish between transaction-construction issues, fee calculation, block-limit pressure, invalid DUST spend proof, and effects-check mismatch.

Sources checked

This guide is based on:

Substrate author-RPC error handling, which defines the upstream BASE_ERROR = 1000 and POOL_INVALID_TX = BASE_ERROR + 10 mapping.
Midnight RPC and networking documentation, which documents Midnight’s JSON-RPC surface and Polkadot SDK RPC support.
Midnight runtime custom-code mapping in midnight-node, pinned to commit 948b7dbcd975ce5a360d83f6353c2b4872482621, which defines the mappings for codes 139, 154, 168, 170, and 186 used in this guide.
Midnight ledger TransactionCostModel documentation, which documents the cost-model API used for transaction cost and block-limit reasoning.
Midnight forum thread on block-limit exhaustion, which discusses 1010 behavior when contract deployment exceeds block limits and names the five cost dimensions used in the block-fullness model.
Midnight.js issue #667, which shows a real 1010 / custom-code debugging case around unshielded NIGHT token operations and fee calculation.
Midnight.js issue #731, which documents a Custom error: 186 effects-check failure case.
Issue #731 validation repository, which provides supporting validation notes for the 186 repro family.

Final checklist

When debugging 1010: Invalid Transaction, ask:

Did I capture the full error object?
Did I inspect error.data?
Is this a built-in invalid transaction reason or Custom error: N?
Did I use the custom code to choose the right first place to investigate?
Am I accidentally treating 1010 as the root cause?
Am I overclaiming what the custom code proves before checking logs and version-specific mappings?
Could this be a five-dimensional cost-model / block-limit problem?
Have I reduced the failing action to the smallest reproducible case?

The core rule is simple: 1010 tells you the transaction was rejected. The inner detail tells you where to look next.