Skip to content

environments.toml docs: examples fail to parse; snake_case network keys silently ignored, so dev falls back to testnet #600

Closed

Description

@Dgetsylver

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

⚠️ Step 3 really funds an account and deploys contracts on testnet.

  1. stellar scaffold init demo --template react -p npm -y && cd demo
  2. 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
  3. 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::MalformedNetwork variant 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.md examples 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)] to Network so typos fail loudly. The v2 schema plan in plan: scaffold.yml proposal #592 already rejects unknown keys.
  • Wire up Error::MalformedNetwork: require name, or both rpc-url and network-passphrase, before handing off to stellar-cli.
  • Move the two printer lines inside the branch that actually starts the container.

Acceptance criteria

  • Pasting any environments.md example 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.

Related: #592, #159


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

  1. zachfedor commented on Oct 5, 2026

    @zachfedor
    Contributor

    Closing because we're deprecating environments.toml in favor of scaffold.yml config file. See #612

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions