Icp-cli fails when .icp/data/mappings/ic.ids.json cache is missing - no fallback to canister_ids.json

Developers
1

@raymondk

Critical points:

  1. Root cause identified: Tool depends on internal cache at .icp/data/mappings/ic.ids.json
  2. No cache rebuild logic: When cache is missing, tool doesn’t read from canister_ids.json
  3. Impact: Any cache loss (cleanup, reinstall, switching machines) makes tool unusable

Proposed fix:

  • Cache should be performance optimization only, not source of truth
  • Auto-rebuild cache when missing
Steps to Reproduce
  1. Run icp deploy -e ic successfully on a project
  2. Delete .icp/data/mappings/ic.ids.json (or entire .icp/ directory)
  3. Run icp deploy -e ic again:
✘ failed to create canister: Insufficient cycles. Requested: 2000000000000 cycles, available balance: 659_650_000_000 cycles. 
                    use `icp cycles mint` to get more cycles or use `--cycles` to specify a different amount.
  1. Run icp canister status backend -e ic:
Error: failed to lookup canister ID for canister 'backend' in environment 'ic'

Caused by:
    could not find ID for canister 'backend' in environment 'ic'
  1. You’re stuck, unless you manually rebuild .icp/data/mappings/ic.ids.json with (example):
{
  "backend": "xxx-cai",
  "frontend": "xxx-cai"
}

Thanks!

2

Hi @jdelforge

Whatever is in .icp/ should actually be checked into source control and not deleted with the exception of the .icp/cache subdirectory. So basically only .icp/cache/ should be in your .gitignore

The .icp/ folder is split into two parts, see Managing Environments | ICP CLI

  • When you start a managed network, the ids go in the cache because they are disposable - if you stop the network it will be recreated from scratch the next time you start it.

  • When you are connecting to a “connected network” those are permanent networks and you presumably paid cycles to get the canister created - for those the canister id should be saved and ideally checked into source control.

canister_ids.json is what dfx uses - it’s not relevant to icp-cli.

Let me know if that makes sense, if you think there is a good place to clarify that or if I’m misunderstanding something.

3

@raymondk

Thanks for the input.
What remains a mystery to me :

  • At what point is ic.ids.json generated ? I’m playing around trying to understand : deleting the file, stopping/starting the server, building/deploying, nothing gets generated… yet at some point the file was generated. How did it know my network canister ids? From where did it get them? I only had canister_ids.json and an old dfx.json mentioning them.

Extra observations

a) icp network: why -d for --background and not -b ?

b) why icp -V and not icp -v ?

c) icp network start: I often get Error: port 8000 is in use by the local network of the project at '/Users/djo/ic_projects/...', yet sudo lsof -i :8000 is giving no result. You mentioned a workaround for this during the last group call but I didn’t catch it — I’ll look into it further.

d) Why no icp init? I often have a folder already created. I have mentioned it a few times, still wonder why not. dfx init for Initializing Projects in Existing Folders

Just general feedback from daily usage — no need to address all of these, I’ll work through them.

Thanks !

4

When you create canisters on that network. So either as part of icp canister create or one of the later steps of icp deploy

5

But what if the canisters already exist on the mainnet?

Then is creating ic.ids.json by hand the way to go?

Instinctively I would add the canister ids in icp.yaml or via a reference to a .env file, but no where in the docs have I seen canister ids being referenced in a icp.yaml.

Thanks !

6

Originally because I thought it would be -d for daemon and that it would be similar to docker run -d but I see that the d in docker is for --detach … maybe we should change it to stay consistent.

Because we wanted to save -v for --verbose and potentially add many levels of verbosity -vvv. We don’t currently have that but maybe we’ll add it later.

Normally it should tell you which directory the network is running in and you can just go to that directory and run icp network stop. I’m on a mac and I can see the open port.

I would suggest you try the following steps:

  1. Go to the directory that is mentioned and run icp network status to make sure there is in fact a netwrok running. If there isn’t please send us some diagnostic info (more details below)
  2. You can try to check explicitly ipv4 (sometimes lsof can be weird) - it should be a pocket-ic process holding the port if you are running a managed network.
lsof -nP -i4  | grep ":8000"

What I mentioned during the call was:

# Check for instances of icp-cli-network-launcher
ps aux | grep icp-cli-network-launcher

# Check for instances of pocket-ic
ps aux | grep pocket-ic

Some diagnostic info you could send us:

  • If you are running a network in a docker container or not
  • The version of icp-cli you are using
  • The OS/Arch you’re on
  • From the project where the network is supposed to be running, the contents of .icp/cache/networks/<network-name>/descriptor.json
  • The content of this directory depending on your OS:
# https://github.com/dfinity/icp-cli/blob/main/crates/icp/src/network/directory.rs#L32-L35
//! - **Windows**: `~\AppData\Local\icp-cli\cache\port-descriptors\`
//! - **macOS**: `~/Library/Caches/org.dfinity.icp-cli/port-descriptors/`
//! - **Linux**: `~/.cache/icp-cli/port-descriptors/`
//! - **With `ICP_HOME`**: `$ICP_HOME/port-descriptors/`
  • The version of the network launcher you are running (you should be able to get that from the path of icp-cli-network-launcher or by checking the content of ~/Library/Application Support/org.dfinity.icp-cli/pkg/network-launcher on a mac.
7

Unfortunately for now, you have to create the ic.ids.json file by hand if you are migrating from dfx.
There are some details here:

8

Hey @jdelforge, I forgot to mention that there actually is a --init on icp new, see the documentation. So you can call it like this:

# Create in the `my-lib` directory
icp new my-lib --subfolder rust --define network_type=Default

# Create in the current directory
icp new my-lib --subfolder rust --define network_type=Default --init

# or simply like this if you want to go through the menu
icp new <project-name> --init
9

Hi @raymondk

Thanks for the follow-up.

Regarding icp network start,

Current error:
Error: port 8000 is in use by the local network of the project at '/Users/djo/ic_projects/pybara/pybara-wallet'

Running from that exact folder:

  • icp network stop gives:
    Error: network 'local' is not running

  • icp network status gives:
    Error: network 'local' is not running

  • lsof -nP -i4 | grep ":8000" gives nothing

ps aux | grep icp-cli-network-launcher

djo 25350 0.0 0.0 435522192 10672 ?? S Thu02PM 0:01.16 /Users/djo/Library/Application Support/org.dfinity.icp-cli/pkg/network-launcher/v12.0.0-2026-01-29-23-28/icp-cli-network-launcher --interface-version 1.0.0 --state-dir /Users/djo/ic_projects/pybara/pybara-wallet/.icp/cache/networks/local/state --gateway-port 8000 --status-dir /var/folders/c7/f39783455gv_mw6bhb25_7h40000gn/T/.tmpiFmAJp djo 30035 0.0 0.0 435299504 1408 s019 S+ 8:03PM 0:00.00 grep icp-cli-network-launcher

ps aux | grep pocket-ic

djo 30383 0.0 0.0 410059936 192 s019 R+ 8:06PM 0:00.00 grep pocket-ic

__

Info:

  • Not running docker
  • icp -V : icp 0.1.0
  • uname -sm: Darwin arm64
  • no descriptor.json inside .icp/...
  • no folder known as ~/Library/Caches/org.dfinity.icp-cli, my Caches/ folder only has 7 folders, so pretty easy to scan, and nothing is related to icp.
  • Everything else works well so far, running canisters on the mainnet. I have abandoned dfx to be able to provide feedback for the new cli.

__

Let me know if you need further information, I’ll be quicker to respond.

Thanks!