Key smart-contract troubleshooting rows to verbatim CLI and compiler errors - #93
Conversation
Agents and humans search a troubleshooting table by pasting the exact error text they got, and the table had no row matching the most common CLI and build failures. Add rows keyed by what the tools actually print: the missing-wasm read error on deploy, the Windows MSVC linker notes, the identity and alias name collisions, and the funding failure that still exits 0 with the key saved but no account created. The missing-wasm case needs more room than a table cell, so it gets a short subsection with both branches: a wasm was built but somewhere else (the workspace-root target/, filename derived from the package name with - as _), or nothing was built at all because the package is not a default member declaring crate-type cdylib. Also correct the identity-missing row, which quoted a message the CLI does not emit.
|
There was a problem hiding this comment.
Pull request overview
Updates smart-contract troubleshooting guidance to match verbatim CLI/compiler errors and provide actionable diagnoses.
Changes:
- Adds error-keyed troubleshooting rows for WASM paths, Windows linking, identities, aliases, and funding.
- Adds detailed workspace/WASM artifact diagnostics.
- Corrects the missing-identity error text.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| | `cannot find macro println` / `std` errors | Missing `#![no_std]` | Add as first line of `lib.rs`; use SDK types | | ||
| | `can't find crate for core` targeting wasm | Missing target | `rustup target add wasm32v1-none` | | ||
| | `reading file target/wasm32v1-none/release/my_contract.wasm: No such file or directory (os error 2)` | The `--wasm` path isn't where the build wrote the artifact — or nothing was built at all | Diagnose both branches: [No wasm at the path you passed](#no-wasm-at-the-path-you-passed) | | ||
| | ``linker `link.exe` not found`` plus ``the msvc targets depend on the msvc linker but `link.exe` was not found`` (Windows) | Host-target linking, **not** the wasm build — `wasm32v1-none` links with the bundled `rust-lld`, so this hits `cargo test` and `cargo install stellar-cli`, never `stellar contract build` | Install Visual Studio 2017+ or Build Tools for Visual Studio with the Visual C++ ("Desktop development with C++") workload — VS Code alone is not sufficient. For the CLI itself, take the prebuilt binary instead: `winget install --id Stellar.StellarCLI` | |
| `stellar contract build` reports the artifact it wrote as `Wasm File:` under `Build Summary:`. That path — not a reconstructed one — is what `--wasm` takes. When it doesn't exist, decide which of two things happened: | ||
|
|
||
| - **A wasm was built, somewhere else.** In a Cargo workspace every artifact lands in the *workspace-root* `target/`, not in the package's own directory, and the filename is the package name with `-` replaced by `_` (package `my-contract` → `my_contract.wasm`). Deploying from inside `contracts/my-contract/` with a relative `target/...` path is the usual version of this. | ||
| - **No wasm was built at all, and the build still exited 0.** Run from the workspace root, the build compiles only workspace *default members* whose `[lib]` declares `crate-type = [..., "cdylib"]` — every other package is skipped silently. Add the `cdylib` crate type (see [SKILL.md](SKILL.md#project-setup)) and check the package is in `workspace.members`. `stellar contract build --package my-contract` (or running from that package's own directory) selects by name instead, and fails loudly — `package my-contract not found` — rather than quietly building nothing. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (4)
skills/smart-contracts/development.md:451
- Checking only
workspace.membersdoes not resolve the silent-skip branch described here. The CLI filters unqualified workspace builds using Cargo'sworkspace_default_members, so a package can already be a workspace member and still produce the same successful build with no artifact whendefault-membersexcludes it. Include that list in the diagnostic.
- **No wasm was built at all, and the build still exited 0.** Run from the workspace root, the build compiles only workspace *default members* whose `[lib]` declares `crate-type = [..., "cdylib"]` — every other package is skipped silently. Add the `cdylib` crate type (see [SKILL.md](SKILL.md#project-setup)) and check the package is in `workspace.members`. `stellar contract build --package my-contract` (or running from that package's own directory) selects by name instead, and fails loudly — `package my-contract not found` — rather than quietly building nothing.
skills/smart-contracts/development.md:439
- The symptom is network-agnostic, but the recovery command always selects testnet. If the failed generation used local or futurenet, this funds the identity on a different network and leaves the original account missing. Tell users to retry against the same network shown in the error (with testnet only as an example).
| `Unable to fund account alice on …`, **and the command still exits 0** | Friendbot request failed. The key *was* saved; the account was never created, so the next command fails on a nonexistent account | Retry with `stellar keys fund alice --network testnet`, which exits non-zero and prints the real cause (`funding failed: …`). Friendbot only exists on testnet/futurenet/local — on mainnet, fund from an already-funded account |
skills/smart-contracts/development.md:450
- The workspace-root location is only Cargo's default.
CARGO_TARGET_DIRor Cargo'sbuild.target-dircan redirect artifacts, and the CLI builds undermetadata.target_directory; describing the roottarget/as universal sends users with either setting to the wrong place again. Qualify the default and mention configured target directories.
- **A wasm was built, somewhere else.** In a Cargo workspace every artifact lands in the *workspace-root* `target/`, not in the package's own directory, and the filename is the package name with `-` replaced by `_` (package `my-contract` → `my_contract.wasm`). Deploying from inside `contracts/my-contract/` with a relative `target/...` path is the usual version of this.
skills/smart-contracts/development.md:436
- This error can occur while using any network, but the prescribed command funds only testnet. For a local or futurenet workflow that leaves the intended account nonexistent. Separate identity creation from optional funding, and use the caller's Friendbot-backed network when funding is required.
This issue also appears on line 439 of the same file.
| `Failed to find config identity for alice` / `invalid signing key or identity name` | CLI identity missing or misspelled | `stellar keys ls` to see what's saved; `stellar keys generate alice --network testnet --fund` to create it |
The MSVC linker row claimed the error never reaches stellar contract build. It does: the wasm links with rust-lld, but a contract build still compiles soroban-sdk's proc-macro crate and its build script for the host, and those need link.exe like any other host artifact. The missing-wasm branch told readers to check workspace.members, while the build filters on default members — a package can be a member and still be skipped. Point at default-members instead. Also drop the bare --overwrite suggestion on an existing identity: it replaces the stored secret irrecoverably, which is not something to reach for casually on a key that may hold funds.
|
🤖 Automated message from Kaan's Automated Triage Bot. Both of Copilot's points were right, and the first one I had independently reached while re-verifying the diff against source: The missing-wasm branch now points at One change of my own: the identity-collision row offered Pushed as 6f30b51. Everything else in the diff I re-checked against upstream source, and the quoted strings all match: |
The workspace-root target/ is Cargo's default, not a rule — CARGO_TARGET_DIR and build.target-dir both move it, and someone who set either would be sent to the wrong place a second time by this very section. Say so, and point back at the printed Wasm File: path as the authority. The funding retry hardcoded testnet while the symptom is network-agnostic; retrying on a different network than the one that failed would leave the account still missing.
|
🤖 Automated message from Kaan's Automated Triage Bot. Copilot's second pass ran against the pre-push head, so its
I left the identity-missing row alone. Its |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (2)
skills/smart-contracts/development.md:424
- This statement overpromises: several existing rows below (for example, “Calls fail after inactivity” and “Temporary data vanished”) are symptom paraphrases, not text emitted by the CLI or compiler. Scope the search instruction so it does not incorrectly imply that every row is keyed by verbatim output.
Rows are keyed by the text the CLI or the compiler actually prints — search this table for the string you got, not for a paraphrase of it.
skills/smart-contracts/development.md:432
- This directly contradicts the PR description, which says this host-linker failure hits
cargo testandcargo install stellar-clibut “neverstellar contract build.” The distinction determines whether users should apply this row to a failed contract build, so reconcile the description and this diagnosis against verified Windows behavior; if this row is correct, update the PR description accordingly.
| ``linker `link.exe` not found`` plus ``the msvc targets depend on the msvc linker but `link.exe` was not found`` (Windows) | Host-target linking. The wasm itself links with the bundled `rust-lld`, but a contract build still compiles `soroban-sdk`'s proc-macro crate and build script *for the host* — so this hits `stellar contract build` as well as `cargo test` and `cargo install stellar-cli` | Install Visual Studio 2017+ or Build Tools for Visual Studio with the Visual C++ ("Desktop development with C++") workload — VS Code alone is not sufficient. For the CLI itself, take the prebuilt binary instead: `winget install --id Stellar.StellarCLI` |
🤖 Automated message from Kaan's Automated Triage Bot.
Closes #53
The troubleshooting table in
smart-contracts/development.mddescribed symptoms in its own words, so pasting a verbatim CLI or compiler error into it matched nothing. This keys the rows to the strings the tools actually emit, for the four failures the issue names. Every string here is quoted from source rather than from memory:reading file <path>: No such file or directory (os error 2)iswasm::Error::CannotReadContractFilein stellar-cli; the two Windows lines are rustc'sLinkerNotFoundandMsvcMissingLinker;An identity with the name '<x>' already existsandalias '<x>' is already referencing contract ...are thekeys generate/keys addandcontract alias adderrors; andUnable to fund account <x> on ...is thekeys generate --fundpath that prints an error and then returnsOk(()), so the key is saved but the account was never created.Two of these needed more than a restatement of the issue. The missing-wasm case gets a short subsection because it really is two different bugs — a wasm was built but under the workspace-root
target/with-swapped for_in the filename, or nothing was built at all because the package is not a workspace default member declaringcrate-type = [..., "cdylib"], in which case the build still exits 0. And the Windows linker failure is a host-target failure only:wasm32v1-nonelinks with the bundledrust-lld, so it hitscargo testandcargo install stellar-clibut neverstellar contract build— worth saying, since the obvious guess is that the contract build is broken.I also corrected the neighbouring identity row, which quoted
Error: identity "alice" not found. The CLI emitsFailed to find config identity for alice(orinvalid signing key or identity name), so that row had the same searchability defect the issue is about.One caveat on verification: this is a markdown-only change under
skills/, and I confirmed fromsite/scripts/copy-skills.mjsandsite/src/lib/skill-meta.mjsthat the site copies companion files verbatim and only ever parsesSKILL.mdfrontmatter plus its first H1, so nothing in the build reads this file's contents. I could not runpnpm lint/lint:ts/buildmyself — the sandbox this ran in blocked the Node toolchain — so CI is the first real execution of those checks. The markdown table was validated by hand: every new row has exactly three cells, no unescaped pipes, and the new#no-wasm-at-the-path-you-passedanchor matches its heading.