Troubleshooting

Use this page when the local workspace fails in a predictable way.

Dependency Install Fails

Check the package manager and Node.js versions:

node --version
pnpm --version

Use pnpm for this project. Mixing npm, yarn, and pnpm can create lockfile and dependency resolution issues.

Build Fails

Common causes:

• TypeScript errors.
• Missing dependencies.
• Invalid environment assumptions.
• Importing runtime-only code into the wrong package.
• Referencing missing assets or model files.

Run:

pnpm build

Read the first real source error before changing unrelated files.

Desktop Provider Calls Fail

For desktop runtime work, confirm:

• Required LLM_*, TASK_*, ASR_*, or TTS_* values are set.
• The provider base URL is reachable.
• PROXY_URL is set only when needed.
• The selected model supports the requested modality or tool-calling behavior.

Do not paste raw provider keys into issues or docs.

Plugin Does Not Load

Check:

• plugin.json exists.
• The manifest entry path is correct.
• The entry module exports the expected hooks.
• Changed .mjs files pass node --check.
• Runtime logs do not show a manifest parse error or module import error.