> For the complete documentation index, see [llms.txt](https://docs.ethernity.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ethernity.cloud/developer-guide/the-guide/reference-and-troubleshooting.md).

# Reference & troubleshooting

The lookup page: every command, every task status code, and the result envelope — with pointers to the page that explains each in depth.

### The SDK commands

| Command        | What it does                                 | Details                                                                                                     |
| -------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `ecld-init`    | scaffold a new dApp project                  | [Build & publish](https://docs.ethernity.cloud/developer-guide/the-guide/build-and-publish-your-first-dapp) |
| `ecld-build`   | bake your backend into the enclave images    | [Build & publish](https://docs.ethernity.cloud/developer-guide/the-guide/build-and-publish-your-first-dapp) |
| `ecld-publish` | register the enclaves on-chain               | [Build & publish](https://docs.ethernity.cloud/developer-guide/the-guide/build-and-publish-your-first-dapp) |
| `ecld-test`    | run a payload locally — no gas, ESR emulated | [Running your dApp](https://docs.ethernity.cloud/developer-guide/the-guide/running-your-dapp)               |
| `ecld-run`     | run a payload on the network                 | [Running your dApp](https://docs.ethernity.cloud/developer-guide/the-guide/running-your-dapp)               |
| `ecld-info`    | read-only enclave & on-chain diagnostics     | [Inspecting your dApp](https://docs.ethernity.cloud/developer-guide/the-guide/inspecting-your-dapp)         |

In the JavaScript SDK, prefix each with `npx`.

### Task status codes

Every task returns a status code with its result. `ecld-test` and `ecld-run` print the name; the runner exposes it on the result object.

| Code  | Name                     | Meaning                                                                                                                   |
| ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| 0     | `SUCCESS`                | The task ran and returned a result.                                                                                       |
| 1     | `SYSTEM_ERROR`           | The executor failed outside your code.                                                                                    |
| 2     | `KEY_ERROR`              | The payload referenced a missing key/name.                                                                                |
| 3     | `SYNTAX_WARNING`         | The payload did not parse.                                                                                                |
| 4     | `BASE_EXCEPTION`         | Your backend raised — the full traceback IS the result; read it.                                                          |
| 5     | `PAYLOAD_NOT_DEFINED`    | No payload was supplied.                                                                                                  |
| 6     | `PAYLOAD_CHECKSUM_ERROR` | The payload failed its integrity check.                                                                                   |
| 7     | `INPUT_CHECKSUM_ERROR`   | The input failed its integrity check.                                                                                     |
| 28    | `IMPORT_ERROR`           | The serverless backend failed to load inside the enclave (missing dependency, bad import).                                |
| 32    | `CONFIG_ERROR`           | The enclave was built without a required value — re-run `ecld-build`.                                                     |
| 33    | `EXECUTION_TIMEOUT`      | The task produced no result within the order duration.                                                                    |
| 34    | `ESR_GAS_LIMIT_EXCEEDED` | State commits exceeded the per-order relayed-gas budget — commit less often or batch keys.                                |
| 35    | `SECURITY_VIOLATION`     | A state commit ran under a caller that was not the task submitter — the ownership check was bypassed.                     |
| 36    | `ESR_NONCE_VIOLATION`    | A commit's idempotency nonce was already used — duplicate suppressed, state unchanged ("already applied", not a failure). |
| 40–49 | operator faults          | The node, not your code, failed; the runner resubmits these automatically.                                                |

### The result envelope

Every result is a structured envelope; the runner decodes it for you:

```json
{ "ecld": 1, "type": "json|text|base64", "data": "...", "esr": { "wallet": "0x...", "entries": [ { "key": "...", "version": 2, "cid": "bafk...", "state": { } } ] } }
```

* Return plain data from your backend and it is encoded automatically — objects as `json`, strings as `text`, bytes as `base64`.
* `ecld_result(data)` (JS: `ecldResult`) attaches the ESR state of every key the task touched (`esr`); `state=False` suppresses it, and the legacy `___etny_result___` still works with no attachment.
* The runner's state cache refreshes from every envelope, which is what makes `esr_read` free for unchanged state — see [Managing dApp State (ESR)](https://docs.ethernity.cloud/developer-guide/the-guide/managing-dapp-state-esr).

### When something fails

* **Locally first.** Reproduce with `ecld-test` — same executor, same codes, no gas. [Running your dApp](https://docs.ethernity.cloud/developer-guide/the-guide/running-your-dapp)
* **Check what is registered.** `ecld-info` shows the network, both enclaves (published / validated / hashes), and ESR state — free. [Inspecting your dApp](https://docs.ethernity.cloud/developer-guide/the-guide/inspecting-your-dapp)
* **Code 4 with a traceback?** That traceback is your backend's real error — the enclave is fine and the order completed.
* **ESR-specific failures** (broken pointer, gas budget, permissions, nonce) — the troubleshooting table on [Managing dApp State (ESR)](https://docs.ethernity.cloud/developer-guide/the-guide/managing-dapp-state-esr).
* **Out of testnet tokens?** [Testnet Faucet](https://docs.ethernity.cloud/testnet/testnet-faucet).