Skip to content
The Shape Book

Troubleshooting

Book examples do not run from the browser

Section titled “Book examples do not run from the browser”
  1. Start shape-server:
Terminal window
cargo run -p shape-server
  1. Start the book UI (Astro Starlight) on port 9090:
Terminal window
cd shape-web/book/book-site
npm run dev -- --port 9090
  1. Verify backend health:
Terminal window
curl http://localhost:9091/v1/api/health

Parse/type errors point to stale docs examples

Section titled “Parse/type errors point to stale docs examples”

If you see syntax mismatches, check that examples use current syntax:

  • from ... use { ... }
  • fn declarations
  • Option<T> / Result<T> (not null-style APIs)

Extension not loading

Section titled “Extension not loading”
  • Confirm [[extensions]] path is correct and points to a built .so.
  • Confirm ABI exports are present (shape_plugin_info, capability manifest/vtable).
  • Check runtime diagnostics for missing required capabilities.

Lockfile issues

Section titled “Lockfile issues”
  • Project mode uses shape.lock.
  • Standalone scripts use <script>.lock.
  • For external-frozen builds, missing artifacts are hard errors.
  • Native artifacts are matched by current host target and fingerprint. If a lockfile came from another machine, rerun in update mode to add a matching native artifact for this host.