Repository navigation
Description
Summary
The network examples in the Environments guide (docs/site/docs/environments.md) can't be used as written.
1. They don't parse. The multi-line inline tables (network = { … } spread over several lines) are invalid TOML 1.0:
error: ⛔ ️parsing environments.toml: TOML parse error at line 2, column 12
|
2 | network = {
| ^
newlines are unsupported in inline tables, expected nothing
2. Their keys are silently ignored. The guide uses rpc_url, network_passphrase, rpc_headers and run_locally, but Network is #[serde(rename_all = "kebab-case")] with no deny_unknown_fields (env_toml.rs#L143-L151). Only rpc-url, network-passphrase, rpc-headers and run-locally are read. The template and the tutorial use kebab-case, which is why they work.
The effect of (2) is surprising. With every network field unset, to_network lets stellar-cli fall back to its default network, so a development environment silently targets testnet. build also prints the Docker success lines even though it started nothing (build/mod.rs#L105-L111):
ℹ️ Starting local Stellar Docker container...
✅ Local Stellar network is healthy and running.
ℹ️ Using network at https://soroban-testnet.stellar.org
It then funds the default account on testnet through friendbot and deploys the workspace contracts there.
Repro
stellar scaffold init demo --template react -p npm -y && cd demo- In
environments.toml, switch the[development.network]keys to snake_case, as the guide shows:[development.network] rpc_url = "http://localhost:8000/rpc" network_passphrase = "Standalone Network ; February 2017" run_locally = true
stellar scaffold build --build-clients development
Expected
- The guide's examples parse and do what they describe.
- A network that can't be resolved is an error, not a fallback to testnet. An
Error::MalformedNetworkvariant already exists for exactly this case but is never constructed (clients.rs#L89-L92). - The "Starting… / healthy" lines only print when a container was actually started and probed.
Suggested fix
- Rewrite the
environments.mdexamples with kebab-case keys and[<env>.network]tables, as in the template. - Either accept the snake_case spellings with
#[serde(alias = "…")], or add#[serde(deny_unknown_fields)]toNetworkso typos fail loudly. The v2 schema plan in plan: scaffold.yml proposal #592 already rejects unknown keys. - Wire up
Error::MalformedNetwork: requirename, or bothrpc-urlandnetwork-passphrase, before handing off to stellar-cli. - Move the two
printerlines inside the branch that actually starts the container.
Acceptance criteria
- Pasting any
environments.mdexample into a fresh project parses and behaves as documented. - A
[development.network]table with unknown or misspelled keys fails with a clear error and never touches testnet.
Reproduced with stellar-scaffold-cli 0.0.27 (cargo binstall, aarch64-apple-darwin), invoked through stellar-cli 25.2.0 on macOS, without Docker.
Activity
zachfedor commentedon Oct 5, 2026
Closing because we're deprecating
environments.tomlin favor ofscaffold.ymlconfig file. See #612