Error Codes
Caatinga error codes are public API. Automation may parse the CAATINGA_* code, but must not parse human-readable messages.
@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 caatinga 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 config failed validation. | Missing required config fields or invalid values. | Fix caatinga.config.ts schema errors. | Fail CI and correct the committed config. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
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_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_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 (25.2.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_ROLLBACK_TARGET_NOT_FOUND | Requested contract ID is not in artifact history. | caatinga rollback --to target was never recorded in history. | Run caatinga inspect or redeploy; use caatinga 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 caatinga build, fix deploy args, then retry caatinga 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_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. |
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_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 caatinga 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 caatinga init, caatinga build, or caatinga 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_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_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 caatinga doctor --network <network>. Deploy the contract with caatinga deploy <contract> --network <network> --source <identity>. Alternatively, provide contractId in the client registration. caatinga 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_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_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_BINDING_CLIENT_NOT_FOUND | Generated binding did not export Client. | Binding output is missing, stale, or incompatible. | Run caatinga 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. | caatinga generate was not run after deploy, so the template's placeholder stub is still imported. | Run caatinga 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_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_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. |
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. |
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 (caatinga 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_DEV_CEREMONY_BLOCKED | ZK operation blocked on mainnet because artifacts came from a dev single-party ceremony. | caatinga zk build, caatinga deploy <verifier>, or caatinga 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 caatinga zk build artifacts without an audited ceremony. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
CAATINGA_DOCTOR_PARTIAL_DEPLOY | Reserved compatibility code for 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. caatinga doctor prints this as an advisory section and does not exit with this code. | Run the per-contract caatinga deploy commands printed by doctor, or deploy the full graph with caatinga 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_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. | Not supported until v1.0 in @caatinga/client — handle signAuthEntry orchestration in application code. Caatinga surfaces this error so you know multi-signer flows are out of scope for the browser adapter today. | Fail CI for invoke paths that require non-invoker signing. | Public code; adding a new code is minor, removal/rename/meaning change is major. |
Stellar installation guidance: https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup