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 (27.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_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_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 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_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_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. |
CAATINGA_POST_DEPLOY_VERIFY_FAILED |
Post-deploy hook verification failed: invoke output did not match expected value. | An expect check failed in postDeploy, postDeployRead, caatinga smoke, or caatinga 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. |
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. | caatinga generate --strict-network (or equivalent) was run for a configured network that has no block in caatinga.artifacts.json. |
Run caatinga 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. |
Stellar installation guidance: https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup