Skip to content

errors.md

Latest commit

 

History

History
94 lines (72 loc) · 3.62 KB

errors.md

File metadata and controls

94 lines (72 loc) · 3.62 KB

Errors & exit codes

Every sunscreen error has three things: a numeric exit code, a stable string code, and an actionable next_step.

Exit codes

Exit Code Meaning
0 — success
1 unexpected a bug — please report with RUST_BACKTRACE=1 output
2 toolchain_missing a required external tool (anchor, solana, …) was not found
3 invalid_config sunscreen.yml failed schema validation
4 user_input conflicting / ambiguous / unrecognized user request
5 missing_workspace no sunscreen.yml found upward from cwd
9 plugin_runtime a plugin crashed, violated the sandbox, or returned a protocol error

Common error codes (string-level)

These are stable identifiers you can match on in scripts. Subset, full list lives in src/error.rs.

Toolchain (exit 2)

code next_step
toolchain_missing.anchor Install via AVM: cargo install --git https://github.com/coral-xyz/anchor avm --locked && avm install latest
toolchain_missing.solana sh -c "$(curl -sSfL https://release.solana.com/stable/install)"
toolchain_missing.pnpm npm i -g pnpm
toolchain_missing.cargo_build_sbf Comes with the solana install — re-run the solana installer

Invalid config (exit 3)

code Trigger
invalid_config.schema Top-level shape doesn't match v1
invalid_config.field.<path> A specific field is wrong (path follows the YAML, e.g. invalid_config.field.plugins.0.version)
invalid_config.version_unknown YAML declares a version newer than this binary supports

User input (exit 4)

code Trigger
user_input.path_conflict Target directory exists (sunscreen refuses to overwrite without --force)
user_input.symbol_exists A scaffold target (instruction, account, …) is already defined
user_input.recipe_preflight A recipe's preflight detected conflicts
user_input.ambiguous_flag Two flags conflict (e.g. --dry-run + --force)
user_input.semver --version argument isn't valid semver
network.rate_limited Faucet returned 429
network.unreachable RPC didn't respond

Missing workspace (exit 5)

code Trigger
missing_workspace No sunscreen.yml in cwd or ancestors

Plugin runtime (exit 9)

code Trigger
plugin_runtime.protocol Plugin emitted invalid JSON-RPC
plugin_runtime.sandbox Plugin tried to write outside workspace or open a forbidden network connection
plugin_runtime.crash Plugin exited unexpectedly (non-zero, no response)
plugin_runtime.manifest Plugin manifest invalid or unreadable

next_step contract

Every error includes a next_step field — a short, imperative sentence telling you what to do. This is part of the stable surface (tested by tests/errors_contract.rs).

Human-readable form:

error: user_input.symbol_exists: instruction "create_post" already exists (exit 4)
next_step: Pass --force to overwrite, or pick a different name.

JSON form:

{
  "status": "error",
  "error": {
    "code": "user_input.symbol_exists",
    "message": "instruction \"create_post\" already exists",
    "next_step": "Pass --force to overwrite, or pick a different name"
  }
}

Reporting bugs

Exit 1 (unexpected) is a bug. Include in the issue:

  • sunscreen --version
  • The full command you ran
  • Output with RUST_BACKTRACE=1
  • sunscreen doctor --json