-
Using dfx instead of icp. The dfx tool is legacy. All commands have icp equivalents — see references/dfx-migration.md for the full command mapping. Never generate dfx commands or reference dfx documentation. Configuration uses icp.yaml, not dfx.json — and the structure differs: canisters are an array of objects, not a keyed object.
-
Using --network ic to deploy to mainnet. icp-cli uses environments, not direct network targeting. The correct flag is -e ic (short for --environment ic).
icp deploy --network ic
icp deploy -e ic
Note: -n / --network targets a network directly and works with canister IDs (principals). Use -e / --environment when referencing canisters by name. For token and cycles operations, use -n since they don't reference project canisters.
-
Using a recipe without a version pin. icp-cli rejects unpinned recipe references. Always include an explicit version. Official recipes are hosted at dfinity/icp-cli-recipes.
recipe:
type: "@dfinity/rust"
recipe:
type: "@dfinity/rust@v3.3.0"
-
Writing manual build steps when a recipe exists. Official recipes handle Rust, Motoko, and asset canister builds. Use recipe: { type: "@dfinity/rust@v3.3.0" } instead of writing shell commands in build.steps — the Rust recipe defaults the Cargo package to the canister name, so no configuration is needed when they match (see Pitfall 21).
-
Not committing .icp/data/ to version control. Mainnet canister IDs are stored in .icp/data/mappings/<environment>.ids.json. Losing this file means losing the mapping between canister names and on-chain IDs. Always commit .icp/data/ — never delete it. Add .icp/cache/ to .gitignore (it is ephemeral and rebuilt automatically). If you have environments using a connected network that gets reset frequently you can add those specific environment mapping files to .gitignore. Never add the entire .icp or .icp/data directory to gitignore.
-
Using icp identity use instead of icp identity default. The dfx command dfx identity use <name> became icp identity default <name> (setter). icp identity default with no argument is the getter — it prints the current default identity, equivalent to dfx identity whoami. The command icp identity use does not exist. Similarly, dfx identity get-principal became icp identity principal, and dfx identity remove became icp identity delete.
-
Confusing networks and environments. A network is a connection endpoint (URL). An environment combines a network + canisters + settings. You deploy to environments (-e), not networks. Multiple environments can target the same network with different settings (e.g., staging and production both on ic).
-
Writing networks or environments as a YAML map instead of an array. Both networks and environments are arrays of objects in icp.yaml, not maps:
networks:
local:
mode: managed
environments:
staging:
network: ic
networks:
- name: local
mode: managed
environments:
- name: staging
network: ic
canisters: [backend, frontend]
-
Forgetting that local networks are project-local. Unlike dfx which runs one shared global network, icp-cli runs a local network per project. You must run icp network start -d in your project directory before deploying locally. The local network auto-starts with system canisters and seeds accounts with ICP and cycles. Stop it when done:
icp network start -d
icp deploy
icp network stop
-
Not specifying build commands for a frontend canister. dfx automatically runs npm run build for asset canisters. icp-cli requires explicit build commands in the recipe configuration:
canisters:
- name: frontend
recipe:
type: "@dfinity/static-site@v0.3.3"
configuration:
dir: dist
build:
- npm install
- npm run build
-
Expecting output_env_file or .env with canister IDs. dfx writes canister IDs to a .env file (CANISTER_ID_BACKEND=...) via output_env_file. icp-cli does not generate .env files. Instead, it injects canister IDs as environment variables (PUBLIC_CANISTER_ID:<name>) directly into canisters during icp deploy. Frontends read these from the ic_env cookie set by the frontend canister (static-site or the legacy asset canister). Remove output_env_file from your config and any code that reads CANISTER_ID_* from .env — frontends use the ic_env cookie, and canister code reads the same variables at runtime (see Canister Environment Variables below and Pitfall 22).
-
Expecting dfx generate for TypeScript bindings. icp-cli does not have a dfx generate equivalent. Use @icp-sdk/bindgen (>= 0.3.0) with @icp-sdk/core (>= 5.0.0 — there is no 0.x or 1.x release) to generate TypeScript bindings from .did files at build time. Use outDir: "./src/bindings" so imports are clean (e.g., ./bindings/backend). The .did file must exist on disk — either commit it to the repo, or generate it with icp build first (recipes auto-generate it when candid is not specified). See references/binding-generation.md for the full Vite plugin setup.
-
Passing { agent } to createActor from @icp-sdk/bindgen. The old @dfinity/agent pattern was createActor(canisterId, { agent }). The @icp-sdk/bindgen pattern is createActor(canisterId, { agentOptions: { host, rootKey } }) — the binding creates the agent internally. Passing { agent } to the new API silently creates an anonymous identity — no error is thrown, but calls return empty data or access denied. See references/binding-generation.md for the correct pattern.
-
Mixing canister-level fields across config styles. When using a recipe, the only valid canister-level fields are name, recipe, sync, settings, and init_args. Fields like candid, build, or wasm are not valid at canister level alongside a recipe — recipe-specific options go inside recipe.configuration. When using bare build (no recipe), valid canister-level fields are name, build, sync, settings, and init_args. The field init_arg_file does not exist — use init_args.path instead (e.g., init_args: { path: ./args.bin, format: bin }). For the authoritative field reference, consult the icp-cli configuration reference.
canisters:
- name: backend
candid: backend/backend.did
recipe:
type: "@dfinity/rust@v3.3.0"
canisters:
- name: backend
recipe:
type: "@dfinity/rust@v3.3.0"
configuration:
candid: backend/backend.did
-
Placing mops.toml where mops cannot find it. mops searches upward from the build working directory. Where to place mops.toml depends on how the canister is defined:
- Inline canisters (defined directly in
icp.yaml): build cwd is the project root. Place mops.toml at the project root next to icp.yaml. A mops.toml in src/backend/ will not be found.
- Path-based canisters (referenced via
canisters/* or ./my-canister, each with its own canister.yaml): build cwd is the canister directory. Place mops.toml in each canister's directory for per-canister dependencies and compiler versions, or omit it to fall back to a shared mops.toml in a parent directory.
When mops.toml is not found, mops build fails because it cannot locate the project configuration. When mops.toml exists but is missing the matching [canisters.<name>] entry, see Pitfall 17.
-
Misunderstanding Candid file generation with recipes. Binding generation tools (e.g. @icp-sdk/bindgen) require a .did file at a known path on disk. Where to configure it depends on the recipe:
Rust — candid goes inside recipe.configuration in icp.yaml:
- If specified: the file must already exist. The recipe uses it as-is and does not generate one.
- If omitted: the recipe auto-generates the
.did via candid-extractor into the build cache (no predictable project path).
To generate and commit it, then add candid: backend/backend.did inside recipe.configuration:
cargo install candid-extractor
icp build backend
candid-extractor target/wasm32-unknown-unknown/release/backend.wasm > backend/backend.did
Motoko (v5 recipe) — mops build auto-generates the .did to .mops/.build/<name>.did.
-
Missing or mismatched [canisters] key in mops.toml. The @dfinity/motoko@v5+ recipe calls mops build <canister-name>, where the name comes from the name field in icp.yaml. mops build requires a matching [canisters.<name>] entry in mops.toml. If the entry is absent or the key does not exactly match (including casing), the build fails with:
No Motoko canisters found in mops.toml configuration
Add the matching entry — the key must equal the name: value in icp.yaml:
[canisters.backend]
main = "src/backend/main.mo"
-
Port 8000 already in use when starting the local network. Two scenarios:
Scenario A — another icp-cli project holds the port. Stop that project's network using --project-root-override (a global flag available on all commands):
icp network stop --project-root-override /path/to/other-project
To run both networks at once instead of stopping one — e.g. parallel git worktrees — set gateway.port: 0 so each gets a free port. See "Parallel local networks (git worktrees)" under How It Works.
Scenario B — a non-icp service holds the port. Configure an alternate port in icp.yaml and read the actual URLs dynamically via icp network status --json rather than hardcoding localhost:8000:
networks:
- name: local
mode: managed
gateway:
port: 8001
icp network status --json
-
icp new hangs in CI without --silent. Without --define flags, icp new launches an interactive prompt that blocks indefinitely in non-interactive environments. Always pass --subfolder, --define, and --silent for scripted use:
icp new my-project --subfolder rust --define project_name=my-project --silent
-
Using the anonymous identity on mainnet. The local network seeds all managed identities — including the anonymous identity, which is the default — with ICP and cycles on start, so local development works out of the box with no identity or cycles setup required. On mainnet this does not apply, and the anonymous identity should never be used: it is shared by anyone, meaning ICP sent to it is publicly accessible and canisters deployed under it are uncontrolled.
Before deploying to mainnet, switch to a named identity:
icp identity list
icp identity default my-identity
Then verify it has funds — a new identity will need to be funded with ICP or cycles before proceeding:
icp token balance -n ic
icp cycles balance -n ic
icp identity account-id
-
Over-specifying (or wrongly omitting) package in the Rust recipe. As of @dfinity/rust@v3.3.0 the package config is optional and defaults to the canister name in icp.yaml. By convention, keep the canister name equal to the [package] name in Cargo.toml and omit package entirely:
canisters:
- name: backend
recipe:
type: "@dfinity/rust@v3.3.0"
canisters:
- name: backend
recipe:
type: "@dfinity/rust@v3.3.0"
configuration:
package: my-project-backend
Omitting package when the names differ causes cargo build to fail with a package-not-found error — set it to the exact [package] name. On recipe versions before v3.3.0, package was required in all cases.
-
Hand-wiring canister IDs with setter methods or deploy scripts. Controller-only setters (setBridge(principal)) called by a post-deploy script — or sibling IDs hardcoded in settings.environment_variables or init args — are unnecessary: icp deploy injects every canister's ID into every canister's settings as PUBLIC_CANISTER_ID:<canister-name>, readable by canister code at runtime with the correct per-environment value (see Canister Environment Variables). Setter wiring is also more fragile: a --mode reinstall silently wipes the stored pointer, while the automatic variables are re-stamped on every deploy.
