Skip to content
Logo

Troubleshooting

Running the stack

The messages in this section come from pnpm stack up. After each fix, run pnpm stack up again.

Docker is not running

pnpm stack up stops with:

Output
[x] Docker daemon not reachable. Start Docker first (menu: docker-up, the Docker app, or your CLI), then run 'up'.

To start Docker, run:

pnpm stack docker-up

The shell can't find dpm

pnpm stack up stops with:

Output
[x] dpm not found on PATH.
    Install it and add ~/.dpm/bin to your PATH: https://docs.canton.network/sdks-tools/cli-tools/dpm#installation
    Then open a new terminal and run 'pnpm stack up' again (menu: Stack up).

Follow the message, then check that the shell finds dpm:

Terminal
dpm version

LocalNet doesn't start

pnpm stack up stops with:

Output
[x] LocalNet did not start.

There are two known causes:

  • On the first run, start can exit during the Splice migrations. Run pnpm stack up again.
  • Another program holds a LocalNet port, such as 2000, 4903 or 5432. Docker names it in the line before the error, after ports are not available.

To find the program that holds a port, run:

Terminal
lsof -nP -iTCP:5432 -sTCP:LISTEN

LocalNet starts but never gets ready

pnpm stack up stops with:

Output
[!] app-user JSON API did not answer at http://localhost:2975/v2/version within 300s
[x] The LocalNet is up but its JSON API never answered. Check 'canton-barebones logs' in <project>/.canton-localnet, then run 'up' again.

Splice can take longer than the 5 minutes pnpm stack up waits. To check the app-user validator, run:

Terminal
curl -sf http://localhost:2903/api/validator/readyz && echo "app-user ready"

Once it prints app-user ready, run pnpm stack up again. If it never does, read the logs:

Terminal
cd .canton-localnet
pnpm exec canton-barebones logs --tail 100
cd ..

Wallet Gateway doesn't start

pnpm stack up stops with:

Output
[!] Port 3030 is held by pid <pid> (<folder>); not starting the Wallet Gateway.
[!] Wallet Gateway did not answer at http://localhost:3030/ within 60s
[x] The Wallet Gateway is not answering on 3030 (log: <project>/.dev-stack/wallet-gateway.log).

The first line shows up only when another program holds port 3030. It names that program's process ID and folder. If the folder is another project, run pnpm stack down there. Otherwise, stop the program.

Without the first line, read the log file the last line names.

Another program holds port 3012

pnpm stack up warns:

Output
[!] Port 3012 is held by pid <pid> (<folder>); not starting the dApp dev server. Free it, then 'pnpm run dev'.

pnpm dev stops with:

Output
error when starting dev server:
Error: Port 3012 is already in use

Wallet Gateway accepts requests only from http://localhost:3012 (allowedOrigins in wallet-gateway.config.json). Free the port instead of moving the dApp. If the warning names another project's folder, run pnpm stack down there. Otherwise, find the program with lsof -nP -iTCP:3012 -sTCP:LISTEN.

Daml SDK and the DAR

sdk-version in daml/daml.yaml names the Daml SDK version we test the stack on, written below as <sdk-version>.

You have no matching Daml SDK

pnpm stack up stops with:

Output
build-dar: no Daml SDK <major>.<minor> installed.
           Install the tested one: dpm install <sdk-version>
[x] The <name>-<version>.dar build failed.
    Fix what build-dar printed above, then run 'pnpm stack up' again (menu: Stack up).

build-dar uses <sdk-version> when you have it, otherwise the newest installed version with the same <major>.<minor>. To install the tested one, run:

Terminal
dpm install <sdk-version>

The DAR build fails on another SDK version

pnpm build-dar ends with:

Output
build-dar: the build failed on Daml SDK <other-version> with exit code <code>.
           It is tested on <sdk-version>: dpm install <sdk-version>

Install <sdk-version> with the command in the message. If the second line is missing, the build failed on <sdk-version> itself. The dpm build output before it shows the Daml errors.

The DAR upload or the bootstrap has no token

pnpm deploy-dar stops with:

Output
deploy-dar needs CANTON_BACKEND_TOKEN: set it in .env to a JWT your participant accepts. On a LocalNet, pnpm stack up or pnpm run mint-token makes one.

In the Amulet Vesting dApp, pnpm bootstrap stops with:

Output
CANTON_BACKEND_TOKEN is required. Generate one with: pnpm run mint-token

pnpm stack up mints the token for you. To mint it yourself, run:

Terminal
pnpm mint-token

Copy the CANTON_BACKEND_TOKEN= line it prints into .env.

There is no DAR to upload

pnpm deploy-dar stops with:

Output
DAR not found: daml/.daml/dist/<name>-<version>.dar

To build the DAR first, run:

Terminal
pnpm build-dar

The filename comes from name and version in daml/daml.yaml. After you change either, pass the new name to pnpm deploy-dar.

The DAR upload fails with HTTP 400

pnpm deploy-dar stops with:

Output
DAR upload failed with HTTP 400

pnpm stack up adds:

Output
[x] Uploading daml/.daml/dist/<name>-<version>.dar to Canton failed.

LocalNet already has a package with the same name and version, but different contents, so the participant refuses yours (KNOWN_PACKAGE_VERSION). LocalNet keeps its packages between runs, even across projects. This happens when:

  • You changed the Daml code without raising version in daml/daml.yaml.
  • Another project, or an earlier run, uploaded a different package with the same name and version.

Raise version in daml/daml.yaml and build again, or start over with an empty LocalNet.

Wallet Gateway

Wallet Gateway asks for a client secret

Enter unsafe.

Wallet Gateway refuses to sign a message

After you press Sign in the gateway's window, it shows:

Output
signMessage is only supported for wallet-kernel wallets, got participant

Your dApp gets Message signing failed for messageId <id>., for example from useSignMessage. Wallet Gateway signs messages only for wallet-kernel parties. Create a party with wallet-kernel as the signing provider, then press Set as primary on it in Parties.

Wallet Gateway rejects a ledgerApi call

The call fails with:

Output
Unsupported get resource: /v2/users/<user-id>/rights

The gateway matches each resource against the JSON Ledger API routes, so a path with values written into it matches none. Write the route as a template and pass the values in path:

ledgerApi call
await ledgerApi({
  requestMethod: 'get',
  resource: '/v2/users/{user-id}/rights',
  path: { 'user-id': userId },
})

Amulet Vesting dApp

The dApp asks you to run the bootstrap

After you connect, the dApp shows:

Output
no vesting operator on this ledger — run pnpm run bootstrap

The bootstrap has not run on this ledger, for example after a LocalNet reset. With LocalNet running and the DAR uploaded, run:

Terminal
pnpm bootstrap

Then reload the dApp.

Start over with an empty LocalNet

Wallet Gateway keeps its parties in .wallet-gateway, so after a reset it still lists the old ones. To clear both, run:

Terminal
pnpm stack down
cd .canton-localnet
pnpm exec canton-barebones reset
cd ..
rm -rf .wallet-gateway
pnpm stack up

pnpm stack up uploads the DAR again, and runs the bootstrap if the project has one. Then log in to Wallet Gateway and create your parties again.