Troubleshooting & FAQ

You see

ERROR: invalid LC_COLLATE locale name: "C.UTF-8"

Why

Your system has no C.UTF-8 locale, so PostgreSQL can’t create the postchain database with it.

Fix

List the locales you have with locale -a, then create the database with one that exists (for example en_US.UTF-8) for both LC_COLLATE and LC_CTYPE. Full steps: Install Chromia CLI.

You see

FATAL: Peer authentication failed for user "postchain"

Why

PostgreSQL on Linux uses peer authentication for local connections, which only accepts a matching OS user.

Fix

In pg_hba.conf, change the method for local connections from peer to md5 (or scram-sha-256), then restart PostgreSQL: sudo systemctl restart postgresql.

You see

ERROR [main] BaseApiInfrastructure Unable to start REST API on port 7740
ERROR [main] CliLauncher Address already in use

Why

Another process, usually a node you started earlier in another terminal, already listens on port 7740.

Fix

Stop the other node (Ctrl+C in its terminal), or find it with lsof -i :7740 and stop it. Then run chr node start again.

You see

Could not auto-detect brid from http://localhost:7740, reason: 503 Client Error: Connection Refused

Why

chr query or chr tx ran while no local node was running, so the CLI couldn’t look up your Blockchain RID.

Fix

Start the node first with chr node start in your project folder and keep that terminal open. Run queries and transactions from a second terminal.

You see

Missing module_args for module(s): lib.ft4.core.admin

Why

Your chromia.yml sets FT4 moduleArgs under blockchains: but not under test:, so chr test has no admin key.

Fix

Repeat the block under test:, as shown below. See Set up your FT4 project.

test:
  modules:
    - test
  moduleArgs:
    lib.ft4.core.admin:
      admin_pubkey: <your admin pubkey>

You see

Unknown Rell version: 0.18.0

Why

compile.rellVersion in chromia.yml is newer than the Rell compiler bundled with your Chromia CLI (or has a typo).

Fix

Run chr --version and set rellVersion to that Rell version or lower (Chromia CLI 0.34.3 ships Rell 0.16.7). To use a newer Rell, upgrade the CLI first.

You see

(chr tx or chr deployment can’t find the key)

Why

chr looks up keys by ID in the .chromia folder of your home directory (~/.chromia), and file keys at the path you pass. The key was created in another folder, by another user or with another ID.

Fix

Create it with chr keygen --key-id=chromia_key and use the same ID (chr tx --key-id=chromia_key …), or pass the file with --secret=<path>. Check what exists with ls ~/.chromia.

You see

chr deployment create … (no "running" status yet)

Why

A Testnet deployment is a proposal the network has to accept. It isn’t live the moment the command returns.

Fix

Check it with chr deployment info --network testnet --blockchain <name> and wait until the chain is running. Make sure your container lease in the Testnet Vault is active and has room. Steps: Deploy to Testnet.

You see

(deployment rejected: the same configuration is already deployed)

Why

Testnet identifies a blockchain by its configuration, so the unchanged Hello World template collides with someone else’s identical deployment.

Fix

Rename the blockchain in chromia.yml to something unique, for example hello_<yourname>, then deploy again.