> ## Documentation Index
> Fetch the complete documentation index at: https://aomi.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Common errors

> Diagnose common failures when building and shipping an Aomi App. Each issue includes its likely cause and a practical fix.

These are the failures contributors hit most often. Each accordion title is the literal error or symptom, so you can search this page for what you see in your terminal.

<AccordionGroup>
  <Accordion title="SDK version mismatch: plugin=X, host=Y">
    <Warning>
      `aomi-run` refuses to load a plugin whose pinned `aomi-sdk` does not match `aomi-run`'s own version. The loader gates on an exact match, so a plugin built against a different SDK never runs.
    </Warning>

    For a local run, pin the plugin's `aomi-sdk` to the version your installed `aomi-run` reports in its boot banner (the `(aomi-sdk X.Y.Z)` on the first line at startup):

    ```toml Cargo.toml theme={null}
    [dependencies]
    aomi-sdk = "=X.Y.Z"   # match the version aomi-run prints at startup
    ```

    When you go to ship, pin instead to the platform's `required_sdk_version` so CI and the backend accept the build. Run `aomi-build sdk check` for the current requirement (it moves often), which can differ from whatever `aomi-run` you have installed.

    <Warning>
      For a ship build, pin exactly to the platform's required version. Run `aomi-build sdk check` to read it, or `aomi-build sdk fix` to set it, then pin with a leading `=`. Do not hardcode a number from this page; it moves.
    </Warning>
  </Accordion>

  <Accordion title="aomi-run: command not found (after installing the toolchain)">
    <Warning>
      Installing with `--features cli` alone builds only `aomi-build`. The `cli` feature does not include `aomi-run`.
    </Warning>

    There are two binaries: `aomi-build` (the `cli` feature) and `aomi-run` (the `dev-runtime` feature). Install with both features so the `dev-runtime` feature builds `aomi-run`:

    ```bash theme={null}
    cargo install aomi-sdk --locked --features cli,dev-runtime
    ```
  </Accordion>

  <Accordion title="No --version flag on the binaries">
    <Warning>
      Neither binary (`aomi-build` and `aomi-run`) accepts `--version`. Running it errors instead of printing a version.
    </Warning>

    Use `--help` to confirm an install and see the available commands:

    ```bash theme={null}
    aomi-build --help
    aomi-run --help
    ```
  </Accordion>
</AccordionGroup>

## Next

<Card title="The CLI toolchain" href="/docs/build/toolchain/aomi-build">
  The full reference for the two Rust binaries: `aomi-build` and `aomi-run`.
</Card>