sauce command; … marks text that varies with your input.
- If you cannot start the tools, check installation or MCP setup.
- If your program will not compile, check compile errors.
- If a chain request fails, check endpoints and rate limits and deployment compatibility.
- If execution fails, check simulation reverts, funding and approvals, or wallets and passwords.
Each error starts with the command’s name, such as
sauce simulate:. Notes and warnings on stderr do not. With --json, a simulation that reverts puts reverted: true and error first in its JSON.
Install and Node
The package needs Node.js 24 or newer.node --version prints yours.
If your shell does not find sauce after npm install -g @eco-incorp/sauce, npm’s global bin directory is not on your PATH. npm prefix -g prints the prefix that directory is under.
Without a global install, npx -y @eco-incorp/sauce <command> runs the command. In a directory whose project does not depend on @eco-incorp/sauce, do not run npx sauce: npx then fetches an unrelated npm package named sauce.
Compile errors
A compile error names the file, the chain and the line, and often ends with ahint:.
A name nothing declares
main’s parameters with its type and pass it with --args, in the order main declares them. If it is a token or protocol, check the spelling with sauce globals --chain <chain>.
A token or contract the chain does not have
main parameter and write Token(token).transfer(…). See Names.
A token or contract another chain has is refused at its use, with the file, line and column and the chains that have it:
if (USDT) { … }, so the branch is compiled only where the chain has it (Names).
A protocol contract that is renamed or ambiguous
A construct SauceScript does not support
if/else. Builtins and the language pages list what compiles.
Using a token write’s result
bool to check. Call it as a statement.
A reserved name
__sauce_approve and __sauce_transferFrom.
Signed and unsigned values in one expression
Int256 and Uint256 do not mix in arithmetic or comparisons. Convert one operand with Int256(value) or Uint256(value). A conversion reverts the cook when the value does not fit the target type.
A negative constant for an unsigned value
Int256. Declare the value as Int256: const delta: Int256 = -10.
An unsupported signed Math helper
Math helpers for division, remainder, shift and comparison are removed. The message names the helper you called and the operator that replaces it. Declare the values as Int256 and use /, %, >>, <, >, <= or >=. Int256.fromBits(x) reads the bits of a Uint256 as a signed value.
A type name used as a variable
Uint256 and Int256 are reserved. Rename the local, parameter, constant, import or function.
An argument of the wrong type
--args value is checked against main’s parameter type before anything is read or built. Give each value in the type its parameter declares. An array or a tuple is JSON (--args '[1, 2]'). A negative Int256 is written as it is: --args -1.
-- is read as an argument, the flags that follow it included. Put -- before a value that starts with --, and keep --args last on the command line when you use it.
Preview-chain refusals
compile and reads work, and tx, run, send, a Pot deployment and reclaim are refused before any network read or key use. The second line of the refusal says how to request support for that chain. No flag lifts the refusal. Chains lists which chains are supported.
Preview status limits building and sending, not simulation: simulate runs wherever the release’s engine and Kitchen are deployed, Optimism included. Where the engine has no code, simulate exits 1 with the released engine … is not deployed on <chain>: this SDK's cook cannot run there (see Release not deployed).
Endpoints and rate limits
A command that reads a chain through a built-in public endpoint prints this on stderr:
A simulation through an endpoint that does not serve
eth_simulateV1 falls back to eth_call. It still reports the result and the gas, but no transfers, and the output names the method it used.
Simulation reverts and --expect-revert
sauce simulate exits 1 when the cook reverts. The first line gives the decoded reason. Here a require in the program failed because the Pot holds less USDC than the program spends. To simulate with a balance the Pot does not hold yet, pass --assume-balance USDC:2. To pull the tokens from your wallet in the same cook, pass --fund USDC:2. See Funding.
--expect-revert <text> checks that the cook reverts. The command exits 0 only when the revert reason contains the text:
require message in your program. The text matches any part of the reason.
A revert with no data
Uint256(value) of a negative Int256, and unsigned negation of a nonzero value, such as -amount with amount: Uint256. Write -Int256(amount) for a signed result. Before a conversion that can fail, add a require with a message, so the revert names the condition:
convert.sauce.ts
Release not deployed, and engine pairing
sauce pot reports whether the release’s engine and Kitchen have code on the chain it reads. Where the engine has none, it says so:
sauce pot --chain <chain> --owner <address> reports the engine as deployed. Where the Kitchen has no code, commands that read its fee or deploy a Pot refuse:
v12Pot.encodeCook, checks the pairing and throws for an engine that the release sets record only for other compilers:
v12EngineAddress().
Pot not deployed and approvals
On an EVM chain, an owner’s Pot is deployed by a transaction of its own, before its first cook. With an endpoint, when the Pot has no code yet,sauce tx prints two transactions and explains on stderr:
--fund plans a token’s transfer between the deployment and the cook, and that note then ends at “Send them in order.” ETH:<amount> adds to the cook’s value instead, with no separate transfer. Without an endpoint, the plan checks no deployment and includes no deployment step: deploy the Pot first. A signer estimates the cook’s gas too low while the Pot has no code. Use the gas that sauce tx prints, or build the cook again after the deployment lands.
sauce run sends the deployment only after you approve it. With no terminal to ask on, or with --json, it stops:
--yes together with a password source that does not prompt.
With
--fund-mode allowance, the run approves the Pot in a transaction of its own and warns:
Wallets and passwords
Password sources
A password comes from exactly one source:--password-env, --password-file, --password-command, or a prompt.
A password file others can read
chmod 600 the message names. The wallet directory gets a warning of its own when others can list it:
Wallet policies
A wallet’s policy is<name>.policy.json beside the wallet. Before each send, the command simulates the transaction to measure what it moves, then holds the result to the policy’s limits. A policy file that others can write is refused when the wallet sends, and sauce wallet list warns about it:
chains, to, native and tokens:
"chains": ["ethereum"] and a run on Base:
Send less, use an endpoint that serves
eth_simulateV1, or change the policy if the limit is wrong. From a wallet whose policy limits a token, fund it with --fund-mode permit, allowance or transfer, not through Permit2. See Wallets and policy.
Solana
Execution fee
The Kitchen charges an execution fee in lamports on every cook.--max-execution-fee caps it:
Lamports and rent
The owner pays the Kitchen’s fee, rent for every new account (the Pot, token accounts, a code buffer, a lookup table) and the transaction fees. Solana’ssimulateTransaction takes no balance overrides, so the owner must hold these lamports for a simulation too:
the fee payer holds less than the execution fee, or end with which the transaction would leave below its rent-exempt minimum. Send the owner more SOL. sauce reclaim lists the code buffers and lookup tables an owner left open, and closes them to return their rent.
Accounts and transaction size
A Solana transaction holds at most 1232 bytes.sauce run stages a large program in a code buffer and puts the cook’s accounts in an address lookup table. Some cooks are still too large:
sauce compile --json reports the cook’s size against the limit before you run it. See Solana.
Compute units
priceLimit, then simulate again.
No try/catch on Solana
require, or split the work into separate cooks.
MCP setup
Runtime packages
sauce mcp loads the MCP SDK and zod, and a Solana simulation in a local copy loads LiteSVM. These are optional peer dependencies of the package. When neither your own copies nor the runtime folder has them, the first use installs the folder. The command refuses where it cannot install:
sauce runtime install, then sauce runtime to see where each package comes from. The runtime folder must belong to you alone. Otherwise the command refuses to load it:
A desktop client does not find sauce
A desktop client (Claude Desktop, for example) may not see your shell’s PATH, so it cannot start a sauce installed under nvm or another version manager. sauce starts with #!/usr/bin/env node, so an absolute path to sauce alone fails with env: node: No such file or directory. In the client’s configuration, set the command to the absolute path that which node prints, and the args to the path that which sauce prints, then mcp:
npx with args ["-y", "@eco-incorp/sauce", "mcp"] needs Node on the client’s PATH too, because npx is a Node.js script.
sauce mcp setup stops at a file
setup refuses a JSON file it cannot parse and exits 2. The files for the agents before it are already written, and those after it are not. Add the entry the message prints to that file by hand, then run setup again with --agent naming the agents after it. See sauce mcp setup.
Wallet tools over HTTP
A project entry pinned to a different version
sauce mcp setup writes npx -y @eco-incorp/sauce@<version> mcp into each agent’s project file. To use the latest package, run npx -y @eco-incorp/sauce@latest mcp setup --force to rewrite the entry, then restart the agent’s session.
