Skip to content

Surface underlying transaction errors in the CLI - #111

Merged
lorisleiva merged 1 commit into
mainfrom
fix/cli-unwrap-transaction-errors
Sep 4, 2026
Merged

Surface underlying transaction errors in the CLI#111
lorisleiva merged 1 commit into
mainfrom
fix/cli-unwrap-transaction-errors

Conversation

@lorisleiva

Copy link
Copy Markdown
Member

This PR fixes the CLI swallowing useful transaction errors when executing an instruction plan (e.g. uploading an IDL). The runOrExport helper called the deprecated low-level transactionPlanExecutor, which threw a generic "The provided transaction plan failed to execute" error that hid the real cause. It now uses the client's sendTransactions method, which unwraps failures into readable messages reporting which transaction failed and its underlying program error.

This fixes the CLI swallowing useful transaction errors when executing an instruction plan (e.g. uploading an IDL). The runOrExport helper called the deprecated low-level transactionPlanExecutor, which threw a generic "The provided transaction plan failed to execute" error that hid the real cause. It now uses the client's sendTransactions method, which unwraps failures into readable messages reporting which transaction failed and its underlying program error.
@lorisleiva

Copy link
Copy Markdown
Member Author

@trevor-cortex

@trevor-cortex trevor-cortex left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary

Swaps the CLI's runOrExport helper from calling the low-level client.transactionPlanExecutor(plan) directly to client.sendTransactions(plan), and tightens the plugin's generic constraint to ClientWithTransactionSending instead of an ad-hoc { transactionPlanExecutor } shape. The practical effect is that a failing transaction now bubbles up as a SOLANA_ERROR__FAILED_TO_SEND_TRANSACTION whose message names the failing transaction and carries the underlying program error, instead of the opaque "The provided transaction plan failed to execute". The top-level handler in cli/index.ts just prints err.message, so the improvement is visible to users with no further changes.

Also adds clients/js/pnpm-workspace.yaml with allowBuilds: { esbuild: false }.

Notes

  • The pnpm-workspace.yaml is a drive-by. It's the pnpm 11 allowBuilds entry that pnpm install now auto-writes for any dependency with a blocked build script. Committing it is the right call (otherwise every install mutates the file), and esbuild: false is safe — esbuild's postinstall is just a fast-path optimisation and it falls back to the optional platform package, so tsup still works. It's just unrelated to the PR title, so worth a line in the description.
  • Stale JSDoc on cliRunOrExport (unchanged lines ~128–129): it still says the helper "executes them through the client's transaction plan executor". Trivial, but since this PR is precisely about moving off that path, might as well update it while you're here.
  • Possible follow-up, not blocking: SOLANA_ERROR__FAILED_TO_SEND_TRANSACTION exposes error.context.logs and error.context.transactionPlanResult. Dumping the program logs under --debug in cli/index.ts would make the "why did my IDL upload fail" case a lot easier to diagnose than the stack trace alone.

For subsequent reviewers

Nothing risky here — two-line behavioural change plus a type-constraint tightening. The one thing worth a manual sanity check is running a command that's expected to fail (e.g. writing metadata with the wrong authority) and confirming the CLI output now names the program error.

Comment thread clients/js/pnpm-workspace.yaml
Comment thread clients/js/src/cli/utils.ts
@lorisleiva
lorisleiva merged commit 89ca041 into main Sep 4, 2026
21 checks passed
@lorisleiva
lorisleiva deleted the fix/cli-unwrap-transaction-errors branch September 4, 2026 11:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants