# Troubleshooting & FAQ · Chromia Docs (concept)

> The errors newcomers hit most often on the path install, Hello World, Testnet: each with the message, the cause and the fix.

Source: https://docs.chromia.com/get-started/troubleshooting/

## invalid LC_COLLATE locale name (not reproduced)

```
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](https://docs.chromia.com/get-started/installation/).

## Peer authentication failed (not reproduced)

```
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`.

## Port 7740 already in use

```
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.

## Could not auto-detect brid

```
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.

## Missing module_args

```
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](https://docs.chromia.com/build/ft4/setup/ft4-setup/).

## Unknown Rell version

```
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.

## Key pair not found (not reproduced)

```
(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`.

## Deployment stays pending (not reproduced)

```
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](https://docs.chromia.com/get-started/create-dapp/deploy-to-testnet/).

## Code identical to an existing dapp (not reproduced)

```
(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.

## FAQ

### Which versions should I use?

Chromia CLI 0.34.3 with Rell 0.16.7 (checked 3 Nov 2026). New projects from `chr create-rell-dapp` pin `rellVersion: 0.16.6`, which works.

### Why is my blockchain called my_rell_dapp?

That’s the name the template gives it in `chromia.yml`; the folder is `my-rell-dapp`. Rename it before you deploy to Testnet.

### Do I need the Blockchain RID locally?

No. `chr query` and `chr tx` detect it from your local node. You need it on Testnet.

### Which FT4 version do the guides use?

FT4 Rell `v1.2.0r` with the TypeScript client `@chromia/ft4` 2.1.0. They were released together, so keep both on these versions.