Problem: JSON / API config errors make the service fail to start —— Trove problem library

What you will run into

You edit the provider or profile config, then ccr start errors out or even crashes; or the service starts but the management UI API returns 500 everywhere. Your config edit broke things, the service won't start, and you don't know which line is wrong.

Why this happens

The config file is extremely sensitive to both syntax and field names:

• JSON syntax error: one extra comma, one missing quote -> parsing fails outright -> the service won't start.
• Field name/structure error: api_base_url, type etc. misspelled or at the wrong level - parsing passes but runtime fails -> management UI API 500.

The actual write surface is ~/.claude-code-router/config.sqlite (measured in this marketplace,）; after a bad edit, restoring the backup rolls it back.

A config-driven service has two independent "gates" at startup: syntax parsing and semantic validation.

The syntax gate sits at the very front — one extra comma or missing quote in JSON and the parser throws outright; the service never gets a chance to start, which is why you see "fails/crashes at startup".

The semantic gate sits after parsing — a misspelled field or wrong nesting level passes JSON parsing, but the service reads the wrong values and only blows up when it reaches the routing/API layer, which is why you see "starts but API 500".

That's why the same kind of edit produces completely different symptoms.

The two gates map to two locating tools: the syntax gate is located in one step by jq empty / python3 -m json.tool (down to the line); the semantic gate can only be checked field by field against the project config docs.

There's also a deterministic safeguard: back up before editing — the config file is state; a backup makes "broke it" reversible instead of irreversible, and restore is a fixed three-step: delete + move back + restart.

Step by step

1. Back up first — Required

cp -r ~/.claude-code-router ~/.claude-code-router.bak

Always back up before editing config; if you break it, there's an undo.

2. Validate the JSON syntax — Required

jq empty <your-config-file>

No output = syntax OK; an error points at the line. Without jq, use python3 -m json.tool <file>.

3. Cross-check fields against the docs — Required

Open the project config docs and check each field like api_base_url, type for name and nesting - don't write from memory.

4. Broke it? Restore the backup and restart — Required

rm -rf ~/.claude-code-router && mv ~/.claude-code-router.bak ~/.claude-code-router && ccr restart

How to confirm it works

After the config is fixed, the service starts normally (expected output shape):

ccr start
-> normal startup logs, no JSON parse errors / crashes

The management UI API no longer returns 500; a test config change saves and takes effect.

Other environments

Symptom

After editing the config, ccr start errors or crashes; the management UI API returns 500.

Cause

provider/profile config JSON syntax error or wrong field names (e.g. api_base_url, type misspelled/wrong structure).

Solution

1. Back up the config file before editing (~/.claude-code-router/).
2. After editing, check the syntax with a JSON validator.
3. Cross-check fields against the project config docs; if you broke it, restore the backup and restart.