Caatinga error codes are public API. Automation may parse the CAATINGA_* code, but must not parse human-readable messages.
Versioning: adding a new code is a minor change; removal, rename, or meaning change is major. Every row below repeats that contract note for release automation.
@caatinga/core also emits non-fatal STELLAR_CLI_* warning codes from the Stellar CLI
compatibility module (evaluateStellarCliCompatibility). Warnings are advisory: they
surface as stderr lines and as Diagnostic.warnings in ctg doctor, but they do
not throw and they do not set a CAATINGA_* exit code. They are not part of the public
error-code table because they are not errors.
| Code | Meaning | Common cause | User action | CI/release action | Versioning note |
|---|---|---|---|---|---|
CAATINGA_CONFIG_NOT_FOUND |
Project config was not found. | Command ran outside a Caatinga project. | Run from the project root or create caatinga.config.ts. |
Fail CI and fix checkout path or project bootstrap. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_DEPENDENCIES_NOT_INSTALLED |
Required npm packages are missing from node_modules. |
caatinga.config.ts imports @caatinga/core but npm install / pnpm install was not run. |
Run npm install or pnpm install in the project root. |
Fail CI and install dependencies before Caatinga commands. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_INVALID_CONFIG |
Project or client config failed validation. | Missing required config fields, invalid values, or a readSourceAccount / options.sourceAccount that is not a G… Ed25519 public key. |
Fix caatinga.config.ts, or pass a 56-character G… key (omit it to use the Stellar null account). |
Fail CI and correct the committed config or the client option. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
| Code | Meaning | Common cause | User action | CI/release action | Versioning note |
|---|---|---|---|---|---|
CAATINGA_STELLAR_CLI_NOT_FOUND |
Caatinga could not find the stellar binary. |
Stellar CLI is not installed or not in PATH. |
Install Stellar CLI using the official Stellar setup guide. | Fail CI and install/pin Stellar CLI in the runner image. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_STELLAR_CLI_VERSION_PARSE_FAILED |
Stellar CLI version output could not be parsed. | stellar --version omitted a valid semantic version. |
Check the installed Stellar CLI and report the unexpected version output. | Fail CI and pin a Stellar CLI version with parseable output. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_UNSUPPORTED_CLI_VERSION |
Stellar CLI version is below Caatinga's hard floor (23.0.0). 22.x cannot sign stellar contract invoke. |
Installed Stellar CLI is too old or is a prerelease below the hard floor. | Install Stellar CLI 23.0.0 or newer (28.0.0 recommended). | Fail CI and upgrade the runner's Stellar CLI. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_UNSUPPORTED_SDK_VERSION |
@stellar/stellar-sdk is below Caatinga's hard floor (16.0.1). |
Installed or resolved SDK is too old for binding generation. | Install @stellar/stellar-sdk ^16.0.1. See SDK version contract. |
Fail CI and pin SDK in package.json. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_STELLAR_SDK_VERSION_PARSE_FAILED |
Could not parse @stellar/stellar-sdk version. |
SDK not installed locally and registry lookup failed. | Run npm install @stellar/stellar-sdk@^16.0.1 or check network access for npm view. |
Fail CI when generate runs without a resolvable SDK. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_RUST_NOT_FOUND |
Caatinga could not find Rust. | rustc is not installed or not in PATH. |
Install or update Rust. | Fail CI and install Rust before Caatinga commands run. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_RUST_TARGET_NOT_FOUND |
Caatinga inferred the Wasm target is missing from a failed build. | stellar contract build failed with CAATINGA_BUILD_FAILED and the combined message/hint/cause mentions wasm32v1-none plus install-style wording (for example “not installed”, “rustup target”). |
Run rustup target add wasm32v1-none and retry; if the heuristic misclassifies, inspect the underlying CAATINGA_BUILD_FAILED output. |
Fail CI and add the target during runner setup. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
| Code | Meaning | Common cause | User action | CI/release action | Versioning note |
|---|---|---|---|---|---|
CAATINGA_COMMAND_FAILED |
An underlying command failed. | Stellar CLI, Cargo, or another tool returned non-zero. | Re-run the printed command directly for full diagnostics. | Fail CI and inspect the underlying command output. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_COMMAND_TIMEOUT |
A subprocess exceeded its timeout and was killed. | A network-facing or transaction command (npm view, npx generate, stellar deploy/invoke) exceeded its budget — stalled registry, wedged network, or hung process. | Check network and registry availability, then retry; the hint reports the limit that was exceeded. | Fail CI; usually a flaky registry or RPC — retry or investigate connectivity. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_UNEXPECTED_ERROR |
An unexpected non-Caatinga error was normalized. | A dependency or internal path threw an unknown error. | Re-run with the latest output and report the underlying message. | Fail CI and capture logs for triage. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ROLLBACK_TARGET_NOT_FOUND |
Requested contract ID is not in artifact history. | ctg rollback --to target was never recorded in history. |
Run ctg inspect or redeploy; use ctg migrate artifacts if on schema v1. |
Fail automation when rollback target is invalid. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ESTIMATE_FAILED |
Deploy fee estimate could not be built or simulated. | WASM missing, deploy args unresolved, or Stellar CLI simulate failed. | Run ctg build, fix deploy args, then retry ctg estimate deploy. |
Advisory in CI; do not block deploy pipelines on estimate alone. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_DEPLOY_FAILED |
Contract deployment failed after command execution started. | Stellar CLI deploy returned an error or deployment output could not be accepted. | Inspect deploy logs, network settings, source account, and artifact path. | Fail CI and retry only after the deploy preconditions are fixed. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_MAINNET_CONFIRMATION_REQUIRED |
Mainnet transaction requires explicit confirmation. | Command targeted mainnet without --yes or CAATINGA_ASSUME_YES=true in non-interactive mode or user declined prompt. |
Pass --yes or set CAATINGA_ASSUME_YES=true in non-interactive CI environments, or confirm prompt. |
Fail CI when mainnet transaction runs unattended without --yes or CAATINGA_ASSUME_YES=true. |
Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_UPLOAD_FAILED |
Contract WASM upload failed after command execution started. | Stellar CLI upload returned an error, or uploaded hash did not match the local WASM file. | Inspect upload logs, network settings, source account, and WASM path. Rebuild if the local hash is stale. | Fail CI and retry only after upload preconditions are fixed. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_BUILD_FAILED |
Contract build failed. | Cargo, Rust target setup, or contract source compilation failed. | Inspect Cargo output and fix the contract build. | Fail CI and treat as a build-blocking error. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_BINDINGS_FAILED |
Binding generation failed. | npx @stellar/stellar-sdk generate failed or required deployment metadata was missing. |
Deploy the contract if needed and rerun ctg generate. |
Fail CI and do not publish stale generated clients. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_INVOKE_FAILED |
Contract invocation failed after target validation. | Stellar CLI invocation, RPC simulation, signing, or submission failed. | Check network, source account, contract ID, method, and arguments. | Fail CI and preserve invocation logs for debugging. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_CONTRACT_NOT_FOUND |
Contract is not configured. | Unknown contract name. | Add the contract to caatinga.config.ts or pass a configured name. |
Fail CI and correct the command or config. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_NETWORK_NOT_FOUND |
Network is not configured. | Unknown --network value. |
Add the network to config or use a configured network. | Fail CI and correct the network selection. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ARTIFACT_NOT_FOUND |
Required artifact is missing. | Missing artifacts file, deployed contract record, or Wasm output. If CARGO_TARGET_DIR is set, Stellar CLI may have written the Wasm outside the configured path. |
Run ctg init, ctg build, or ctg deploy as appropriate. If CARGO_TARGET_DIR is set, unset it or update wasm in caatinga.config.ts to point to the real target directory. |
Fail CI and ensure prerequisite jobs publish artifacts. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ARTIFACT_INVALID |
Artifact file failed validation. | Malformed JSON or unsupported artifact version. | Fix or regenerate caatinga.artifacts.json. |
Fail CI and regenerate artifacts from a valid Caatinga version. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ARTIFACTS_LOCK_TIMEOUT |
Timed out waiting for the caatinga.artifacts.json lock. |
Another Caatinga process is writing artifacts, or an interrupted run left a lockfile whose owner cannot be identified. | Check whether another Caatinga process is running; if none is, remove the reported .lock file and retry. |
Serialize jobs that write artifacts for the same project. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_CONTRACT_ID_NOT_FOUND |
Stellar CLI output did not include a contract ID. | CLI output format changed or deploy did not complete. | Check Stellar CLI output and update parser fixtures if needed. | Fail CI and pin/update Stellar CLI compatibility before release. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_WASM_HASH_NOT_FOUND |
Stellar CLI output did not include a WASM hash. | CLI upload output format changed or upload did not complete. | Check Stellar CLI output and update parser fixtures if needed. | Fail CI and pin/update Stellar CLI compatibility before release. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_CONTRACT_DEPENDENCY_NOT_FOUND |
A configured contract dependency could not be resolved. | Dependency name is missing from config or references an unknown contract. | Add the dependency contract to config or fix the dependency name. | Fail CI and fix the dependency graph before deployment. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_CONTRACT_DEPENDENCY_CYCLE |
Contract dependencies contain a cycle. | Two or more contracts depend on each other directly or indirectly. | Break the cycle or split initialization into a later invoke step. | Fail CI and reject the cyclic dependency graph. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_CONTRACT_DEPENDENCY_ARTIFACT_NOT_FOUND |
A dependency artifact needed for deploy arguments was missing. | Dependency deployment did not run or artifacts were not persisted. | Deploy dependencies first and ensure artifacts are loaded from the selected network. | Fail CI and require dependency artifact restoration before deploy. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_DEPENDENCY_CONTRACT_NOT_FOUND |
A dependency contract ID from artifacts is not present on the selected network. | Stale or wrong-network artifact, typo in contract ID, or dependency was never deployed on-chain. | Redeploy the dependency on the target network, fix caatinga.artifacts.json, or omit --verify-deps. |
Fail CI when --verify-deps is enabled and on-chain verification is required. |
Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_DEPLOY_ARG_PLACEHOLDER_INVALID |
A deploy argument placeholder is malformed or unsupported. | Placeholder syntax is invalid or references an unsupported field. | Use the documented placeholder format for dependency contract IDs. | Fail CI and fix the committed deploy argument template. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_DEPLOY_ARG_PLACEHOLDER_UNRESOLVED |
A deploy argument placeholder could not be resolved. | Dependency artifact data is missing or the current deploy path cannot pass init arguments. | Deploy dependencies first or remove unsupported placeholders. | Fail CI and do not deploy with unresolved placeholders. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_DOCTOR_PARTIAL_DEPLOY |
Reserved: not emitted by any command. Kept for compatibility (partial deploy coverage on a network). | One or more contracts in caatinga.config.ts lack deployment records in caatinga.artifacts.json for the selected network. ctg doctor prints this as an advisory section and does not exit with this code. |
Run the per-contract ctg deploy commands printed by doctor, or deploy the full graph with ctg deploy --network <name> --source <identity>. |
Use deploy coverage output as a pre-flight checklist; doctor exit code reflects toolchain readiness only. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_POST_DEPLOY_VERIFY_FAILED |
Post-deploy hook verification failed: invoke output did not match expected value. | An expect check failed in postDeploy, postDeployRead, ctg smoke, or ctg read --expect. |
Check contract state and the expect value in config or CLI. Prefer structural matchers such as { matcher: "isArray" } when integration tests mutate on-chain state. |
Fail CI when post-deploy or smoke verification fails. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ADDRESS_ALIAS_UNRESOLVED |
Method argument looked like a CLI identity alias but could not be resolved to a Stellar Address. | A post-deploy, invoke, or read arg value was treated as a CLI alias (for example alice) and stellar keys address failed. |
If the arg is a plain String, escape it with a leading backslash (--name '\Dione') or pass --no-resolve-aliases. Otherwise use ${source.address}, a resolved G... address, or create the identity first. |
Fail CI when alias resolution fails during contract calls. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_NETWORK_ARTIFACTS_MISSING |
Generate or smoke requested a network with no deployment artifacts. | ctg generate --strict-network (or equivalent) was run for a configured network that has no block in caatinga.artifacts.json. |
Run ctg deploy --network <name> --source <identity> before generate. |
Fail CI when bindings generation runs before deploy on the target network. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
| Code | Meaning | Common cause | User action | CI/release action | Versioning note |
|---|---|---|---|---|---|
CAATINGA_SOURCE_ADDRESS_UNRESOLVED |
The deploy source address could not be resolved. | ${source.address} was used without --source, or the Stellar CLI identity does not exist. |
Pass --source <identity> and create the identity with stellar keys generate. |
Fail CI and ensure the deploy identity exists on the runner. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_SOURCE_ACCOUNT_REQUIRED |
Deploy/invoke needs a source account. | --source was omitted. |
Pass a local Stellar CLI identity alias, for example --source alice. |
Fail CI and provide the configured identity alias secret. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_SOURCE_IS_SECRET_KEY |
A Stellar secret key (S...) was passed as --source. |
Raw secret key string used instead of a CLI identity alias. | Use a local Stellar CLI identity alias, for example --source alice. |
Fail CI immediately and rotate the exposed secret key. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_SOURCE_IS_SEED_PHRASE |
A seed phrase was passed as --source. |
Multi-word mnemonic or phrase with spaces used as --source. |
Use a local Stellar CLI identity alias, for example --source alice. |
Fail CI immediately; never log or persist seed phrases. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_SOURCE_IS_PUBLIC_KEY |
A public account address (G...) was passed as --source. |
Caller passed a public G... address to --source; deploy/invoke require a local Stellar CLI identity alias. |
Use a Stellar CLI identity with a secret key, for example stellar keys generate alice --fund --network testnet, then --source alice. |
Fail CI and fix scripts to use an identity alias. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_UNSAFE_SOURCE_ACCOUNT |
Source account shape is unsafe but not a recognized secret, seed, or public key. | Malformed G...-like value or other unrecognized unsafe --source input. |
Use a local Stellar CLI identity alias, not key material or addresses. | Fail CI and audit logs for accidental secret exposure. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_INVOKE_TARGET_INVALID |
Invoke target did not use contract.method. |
The invoke target had missing or extra segments. | Use a target such as counter.increment. |
Fail CI and fix the scripted invoke target. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
| Code | Meaning | Common cause | User action | CI/release action | Versioning note |
|---|---|---|---|---|---|
CAATINGA_CONTRACT_ARTIFACT_NOT_FOUND |
Client could not resolve a deployed contract artifact. | The selected network is missing from artifacts, the contract was not deployed on that network, or no explicit contractId was passed. |
Run ctg doctor --network <network>. Deploy the contract with ctg deploy <contract> --network <network> --source <identity>. Alternatively, provide contractId in the client registration. ctg build alone does not register a contract ID. |
Fail CI and make deploy artifacts available to client tests. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_BINDING_CLIENT_NOT_FOUND |
Generated binding did not export Client. |
Binding output is missing, stale, or incompatible. | Run ctg generate <contract> --network <network>. |
Fail CI and regenerate bindings before publish. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_BINDING_METHOD_NOT_FOUND |
Requested binding method was not found. | Contract method name is wrong or bindings are stale. | Check the method name or regenerate bindings. | Fail CI and update generated bindings or tests. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_PLACEHOLDER_BINDING |
The app is still using the scaffolded placeholder binding instead of real generated bindings. | ctg generate was not run after deploy, so the template's placeholder stub is still imported. |
Run ctg generate <contract> --network <network>, then restart the dev server. |
Fail CI and generate bindings before building the frontend. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_XDR_BUILD_FAILED |
Client could not build or read transaction XDR. | Binding transaction object is incompatible or lacks toXDR(). |
Regenerate bindings or provide a compatible binding adapter. | Fail CI and block release until client bindings can build XDR. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_XDR_PREPARE_FAILED |
Client could not complete the binding prepare() step. |
Thrown only when the transaction exposes prepare(); simulation/RPC failed, prepare() threw a non-Caatinga error, or the prepared value could not be read as XDR afterward. |
Check RPC connectivity, simulation errors, and binding compatibility; omit or fix prepare() in custom adapters if unused. |
Fail CI for deterministic tests; mark external RPC outages separately. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_SIMULATION_ACCOUNT_NOT_FOUND |
The wallet source account does not exist on the selected network. | Simulation or account lookup returned ACCOUNT_NOT_FOUND, txNO_ACCOUNT, or equivalent account-not-found text. |
Fund the account with enough XLM to create it and cover transaction fees, or use an existing funded account. | Fail CI when a required source account is missing; fund or select the intended account. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_SIMULATION_RESOURCE_LIMIT |
Soroban simulation exceeded a resource limit or rejected its resource fee. | RPC simulation reported a resource limit, budget exhaustion, or insufficient resource fee. | Inspect RPC diagnostics; reduce contract resource use or use the simulation's required transaction data and fee when building a custom transaction. | Fail CI for deterministic contract resource failures; investigate ledger-dependent fees separately. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_SIMULATION_ENTRY_ARCHIVED |
Simulation needs archived Soroban state restored before the invocation can proceed. | RPC or a generated binding reported ENTRY_ARCHIVED, an expired-state error, or a restorePreamble. |
For invoke(), pass { restore: true } to let a compatible generated binding request wallet approval and submit its RestoreFootprint transaction before retrying. |
Fail CI if restoration is expected but cannot complete; verify the restore and retry flow. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_XDR_SIGN_FAILED |
Wallet failed to sign the prepared XDR. | wallet.signTransaction() rejected, threw, or returned unusable output (wrong network, user rejection, adapter bug). |
Connect the wallet, confirm network/passphrase, and approve the transaction. | In browser CI, fail mocked wallet tests; in manual flows, prompt user retry. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_XDR_SUBMIT_FAILED |
Client could not submit signed XDR. | RPC rejected the transaction or binding submit method failed. | Check signature, RPC URL, network passphrase, and account state. | Fail CI and preserve RPC response details. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_XDR_RESULT_FAILED |
Submit returned a non-null object without a recognized transaction id or result field. | After a successful signAndSend/send call, the value is an object that lacks txHash, transactionHash, hash, and result (null and non-objects are accepted without this code). |
Inspect debugRaw output and align the binding adapter with the expected submit return shape. |
Fail CI and capture the raw result payload. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_READ_RESULT_MISSING |
A simulated read did not expose a return value. | contract(name).simulate() completed preparation, but the generated binding output lacked a usable result property. |
Confirm the method returns a value, regenerate bindings, or rerun with debugRaw to inspect the binding output. |
Fail CI and update the binding adapter or test fixture before release. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_WALLET_NOT_CONNECTED |
Wallet public key could not be obtained before building the binding client. | wallet.getPublicKey() rejected or threw (extension locked, disconnected, not installed, or user denied access); failures that are already Caatinga errors are rethrown unchanged. |
Connect the wallet, grant account access, and retry. | Fail automated wallet tests with fixture setup; surface as retryable in UI flows. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_WALLET_TIMEOUT |
Wallet operation exceeded the optional client timeout. | wallet.getPublicKey() or wallet.signTransaction() did not settle within walletTimeout ms on CaatingaClientConfig (no default when omitted). |
Ensure the adapter rejects on user dismissal, connect the wallet, approve the transaction, or increase walletTimeout. |
Fail automated tests with fake timers; surface as retryable in UI flows. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_WALLET_NETWORK_MISMATCH |
Wallet reports a different network than the app before an invoke is signed. |
The adapter implements getNetworkPassphrase() (the Freighter and Stellar Wallets Kit adapters do) and the wallet is on another network than config.network.networkPassphrase, for example Freighter on Testnet while the dApp targets mainnet. Wallets that cannot report their network are not blocked. |
Switch the wallet to the network named in the hint, or point the app at the wallet's network. | Fail wallet integration tests that use a mismatched fixture network. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_MULTI_AUTH_REQUIRED |
A contract invoke needs non-invoker signatures (delegated Soroban address credentials / "AddressV2"). | AssembledTransaction.sign raised NeedsMoreSignaturesError: the simulated transaction contains unsigned auth entries for accounts other than the invoker/source. |
Multi-auth is application-owned in @caatinga/client — handle signAuthEntry orchestration in application code. Caatinga surfaces this error when the browser adapter cannot satisfy non-invoker auth. |
Fail CI for invoke paths that require non-invoker signing. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
| Code | Meaning | Common cause | User action | CI/release action | Versioning note |
|---|---|---|---|---|---|
CAATINGA_TEMPLATE_NOT_FOUND |
Requested template directory was not found. | Template name is wrong or templates directory is unavailable. | Use a bundled template or configure the templates directory override. | Fail CI and install or reference the expected template. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_INVALID_TEMPLATE_MANIFEST |
Template manifest exists but cannot be parsed or validated. | JSON.parse threw (SyntaxError) or TemplateManifestSchema rejected the document (ZodError) — not version/compatibility mismatches after a successful parse. |
Fix caatinga.template.json so it is valid JSON and matches the template manifest schema. |
Fail CI and block publishing the template package. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_TEMPLATE_MANIFEST_NOT_FOUND |
Template has no manifest. | Template predates manifest compatibility. | Add caatinga.template.json. |
Fail CI and require manifests for all bundled templates. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_TEMPLATE_INCOMPATIBLE |
Template manifest parsed successfully but fails Caatinga compatibility checks. | caatinga.templateVersion is not CURRENT_TEMPLATE_VERSION, or compatibleCore does not satisfy the running @caatinga/core version (for example ^0.1.0 does not include core 0.2.0 under semver 0.x caret rules). |
Use a compatible template or bump official template compatibleCore to ^<coreVersion> (see defaultCompatibleCoreRange() in @caatinga/core) with a matching Caatinga release. |
Fail CI and update template compatibility metadata; official-templates-manifest.test.ts guards bundled templates. |
Public code; adding a new code is minor, removal/rename/meaning change is major. |
| Code | Meaning | Common cause | User action | CI/release action | Versioning note |
|---|---|---|---|---|---|
CAATINGA_ZK_VERIFICATION_FAILED |
On-chain ZK proof verification returned false. |
The submitted proof does not match the verification key or public signals. | Regenerate the proof with correct inputs (ctg zk prove) and retry. Inspect public.json to confirm the expected public signals. |
Fail CI and verify circuit inputs and proof artifacts are consistent. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ZK_VK_REQUIRED |
A zero-knowledge operation requires a verification key. | The requested ZK operation was started without a verification key artifact. | Provide the verification key generated for the circuit and retry. | Fail CI and verify the circuit artifacts are complete. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ZK_INVOKE_FAILED |
A zero-knowledge contract invocation failed. | The verifier invocation was rejected or returned an invocation error. | Inspect the contract and invocation arguments, then retry with valid proof inputs. | Fail CI and inspect verifier invocation diagnostics. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ZK_DOWNLOAD_FAILED |
A required zero-knowledge artifact could not be downloaded. | The artifact host was unavailable or the download failed. | Check network access and artifact availability, then retry. | Fail CI and verify artifact hosting. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ZK_UNSUPPORTED_PLATFORM |
A zero-knowledge operation is unavailable on the current platform. | The requested ZK tool or artifact has no supported build for the current operating system or architecture. | Run the operation on a supported platform or provide a compatible tool build. | Fail CI on unsupported release targets. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ZK_DEV_CEREMONY_BLOCKED |
ZK operation blocked on mainnet because artifacts came from a dev single-party ceremony. | ctg zk build, ctg deploy <verifier>, or ctg zk invoke detected .artifacts/zk/<circuit>/ceremony.json with type: dev-single-party while the target network is mainnet. |
Use testnet for dev workflows, supply audited MPC ceremony artifacts for production, or pass --allow-dev-ceremony only for conscious testing (not for real deployments). |
Fail CI when mainnet jobs use default ctg zk build artifacts without an audited ceremony. |
Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ZK_PROTOCOL_VERSION_UNSUPPORTED |
The target network is below the protocol version the ZK verifier requires. | ctg deploy <verifier> or ctg zk invoke ran against a network whose protocol version (fetched via Soroban RPC getNetwork) is below 27. The verifier is built with soroban-sdk 27, which declares protocol 27 in its wasm. |
Upgrade the network, or target a network at protocol 27 or newer. ctg doctor reports the protocol version of every configured network as an advisory check. |
Fail CI and pin a network that has reached protocol 27. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ZK_INPUT_CONTAINS_PUBLIC_SIGNALS |
The circuit input file contains public signals, which are not allowed. | circuits/input.json included a signal the circuit declares as public (a derived output, such as c in the multiplier scaffold) instead of only private witnesses. |
Remove the public signals from circuits/input.json. snarkjs derives public signals during proving and writes them to .artifacts/zk/<circuit>/public.json. |
Fail CI and keep circuit inputs limited to private witnesses. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ZK_EMBED_VK_UNSUPPORTED |
--embed-vk invoke requested without a generated verification key. |
ctg zk invoke --embed-vk was requested, but contracts/verifier/src/vk.rs is missing or still the scaffold placeholder. |
Run ctg zk build <circuit> --embed-vk, then ctg build verifier and redeploy/upgrade the verifier. Or use the dynamic VK flow (verify_proof). |
Fail CI; generate vk.rs in the build step before any --embed-vk invoke. |
Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ZK_CEREMONY_INCOMPATIBLE |
Ceremony artifacts do not match the circuit being built. | ctg zk import-ceremony was given MPC artifacts (powers-of-tau, circuit_final.zkey, verification_key.json) that belong to a different circuit; the constraint count or verification key does not match .artifacts/zk/<circuit>/main.r1cs. |
Re-run the trusted setup for this circuit, or import ceremony artifacts produced from the same circuit source. | Fail CI and verify the ceremony artifacts match the circuit build. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_ZK_CEREMONY_TAMPERED |
Imported ceremony artifacts no longer match what was pinned at import, or do not verify against each other. | Mainnet ctg deploy <verifier> or ctg zk invoke found circuit_final.zkey, verification_key.json or the .ptau changed or missing since ctg zk import-ceremony (or a hand-written mpc-multi-party manifest with no hashes); or ctg zk verify-ceremony found the zkey does not derive from the circuit and powers-of-tau, or the VK is not the zkey's. |
Restore the original ceremony files or re-import them after auditing where the change came from; run ctg zk verify-ceremony before deploying. --allow-dev-ceremony does not waive this check. |
Fail CI; treat as a possible supply-chain compromise of the trusted setup. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
ZK_CHECKSUM_MISMATCH |
Downloaded (or cached) circom binary did not match its pinned SHA-256. |
ensureCircom verifies every circom binary — freshly downloaded from the GitHub release or read from ~/.caatinga/zk-tools cache — against a checksum pinned in packages/zk/src/install/lazy-install-zk-tools.ts. A mismatch means the release asset or the local cache entry was tampered with, or the pin is stale for a new platform/version. |
The mismatching file is deleted automatically. Do not retry blindly — verify the release asset against GitHub yourself before re-running ctg zk build. If this is a legitimate new platform/version, the checksum pin needs updating in Caatinga itself. |
Fail CI; treat as a possible supply-chain compromise, not a flaky download. | Introduced in the fix for unverified Circom downloads (see Security fixes); public error code, same versioning rules as other ZK codes. |
Stellar installation guidance: developers.stellar.org — setup.