Repository navigation
scaffold.yml missing-version error gives wrong advice and links a 404 #607
Description
Summary
When scaffold.yml is missing, init and watch fail with the error below. It happens, for example, with init --template <repo> on any template that predates scaffold.yml.
error: scaffold.yml is missing or has no 'version' field. If migrating from environments.toml, rename it to scaffold.yml and add 'version: 1' at the top. See https://github.com/stellar-scaffold/cli/blob/main/CHANGELOG.md for details.
The message has two problems (scaffold_yml.rs#L9-L20):
- The advice is wrong for schema v1. "rename environments.toml to scaffold.yml" would break the project: both files coexist.
scaffold.ymlholdsversionandconfig, whileenvironments.tomlstill holds networks, accounts and contracts. - The link is broken.
https://github.com/stellar-scaffold/cli/blob/main/CHANGELOG.mdreturns 404; changelogs live per crate, e.g.crates/stellar-scaffold-cli/CHANGELOG.md.UnsupportedVersionuses the same link.
Suggested fix
- Tell users to create a
scaffold.ymlcontainingversion: 1, and show the minimal file. - Link to the Environments docs page or to the crate changelog.
Acceptance criteria
Following the error message's instructions produces a working project, and its link resolves.
Related: #602 (the tutorial path that hits this error)
Reproduced with stellar-scaffold-cli 0.0.27 (init --template stellar-scaffold/ui#tutorial). The 404 was checked with curl.
Activity
sharmis-tp commentedon Oct 9, 2026
Hi, I'd like to take this one. My plan is to correct the migration advice, replace the 404 link with the current scaffold.yml docs, and add a test that checks the message. Does that match what you have in mind?
zachfedor commentedon Oct 17, 2026
Hey @sharmis-tp, thanks for the offer! I already had a bit of this fix in progress, and it landed in #614 and #615 . I still have plans to split the error into either "missing" or "incorrect version," but I don't want to do that until we fully deprecate use of
environments.toml. Until then, a missingscaffold.ymlisn't a problem as long as it's on the legacy config. If you want, I'd appreciate a test and any feedback you have on the new configuration schema!sharmis-tp commentedon Oct 18, 2026
Thanks @zachfedor, makes sense to wait on the missing vs. incorrect split until environments.toml is gone. I'll open a small PR with a test that checks the version errors' advice actually works (adding the suggested
version: 2line to a version-less scaffold.yml passescheck_version) and that their repository links point at files that exist, so the 404 can't come back unnoticed.One piece of schema feedback from reading through it:
UnsupportedVersionsends v1 users to the crate CHANGELOG "for migration instructions", but the v1 to v2 steps only live in the "Legacy: environments.toml" section of the configuration docs (https://stellarscaffold.org/docs/configuration#legacy-environmentstoml). Pointing both errors there would take people straight to the checklist. Happy to fold that into the same PR if you'd like.Also, #608 (watch dropping changes saved during a rebuild) is still open, and I'd be glad to take it if it's useful.
test(config): check version errors give working advice and live links