Troubleshooting

Start with the exact command, client, and non-sensitive error class. Keep raw configurations, credentials, receipt paths, and private tool results out of public reports.

The package cannot be found

The selected package is @npmmo/roster. Check the current installation and publication status. If it is not published, use the source path rather than changing the command to the unrelated unscoped package.

A registry error is not a reason to run an unknown package with a similar name.

roster is not found after an npx command

This is expected: npx downloads and runs a package without adding a global roster executable. Keep the pinned npx prefix shown in these guides; select Windows for the npx.cmd form. Use the built source entry point for source installations, or choose the optional global installation in the first-run guide if you prefer a bare roster command.

macOS / Linux

npx --yes @npmmo/roster@0.0.4 --help

Windows

npx.cmd --yes @npmmo/roster@0.0.4 --help

There is no roster --version flag. If an existing roster command behaves differently, inspect its package and path.

PowerShell blocks an npm script

Choose the Windows command tab. It uses npx.cmd or npm.cmd, avoiding the PowerShell script shim without changing execution policy. Do not disable machine security controls to run a copied command.

The source build cannot load a native module

Check the Node version and use the repository’s pinned pnpm version. Native dependencies need to match the runtime that runs the CLI. After changing Node versions, reinstall or rebuild dependencies through the package manager in that checkout.

Do not disable dependency security policies or copy native binaries from unrelated projects to get a green run.

Init finds no client configuration

Discovery only reads existing known paths. Open or configure your MCP client first, or manually configure an authorized command-backed server. Review the candidate path order, including home-scope precedence and the current working directory.

init is not an installer for every client and does not create their configuration files. A malformed configuration is reported in discovery rather than interpreted as an empty successful setup.

Sync refuses a URL-only server

The routing boundary is currently command-backed stdio. A URL in discovery does not make it a routable backend. Do not delete that server or wrap it in an arbitrary executable just to make sync pass.

Keep your existing setup, or choose an authorized stdio configuration supported by that backend’s own documentation.

The client cannot launch Roster

Check the path printed by scoped sync and the launcher it wrote, locally. A source or global launcher refers to that installation and Node executable; moving or removing them can break it. An npx-cache installation writes a scoped package launcher instead of a temporary cache path, so it can fetch the package again after cache removal. That refetch needs npm registry access.

Keep source/global installations in a stable location. Re-run scoped sync from the installation you intend to use, or restore the old configuration using its preserved backups before deliberately changing paths. Do not force-delete ownership records.

The client launches serve; a second terminal process is not required. Reconnect the client’s MCP session after a config or mode change.

I still see every tool

Transparent mode is the default. Enable five mode in the existing Roster configuration and restart the router connection. In five mode the exposed tools are draft and call.

Roster does not automatically switch modes when a context threshold is reached.

Codex asks to approve draft or call

A client can require approval for five-mode meta-tools. The generic call tool may invoke a mutating backend, so it must not be treated as universally read-only. A noninteractive Codex run with approval policy never cannot answer a required approval prompt.

Use the client’s documented approval flow for the actions and context you intend to allow. The recorded Codex acceptance tests used invocation-scoped approvals for disposable fixtures; that is not a recommendation to auto-approve every production call or disable global safeguards.

My draft seems unrelated

Describe the next action more specifically. Check that the expected backend connected and that the capability is not drift-quarantined. Sparse lexical matches can be filled by rating-based fallback, so a full lineup is not proof that every candidate is relevant.

Optional dense retrieval can improve semantic matching when available, but it is not a correctness guarantee. You can remain lexical indefinitely.

A skill is missing

Check that its library is included, its child directory contains SKILL.md, and a same-slug skill from an earlier source is not taking precedence. Skills appear through the five-mode bridge, not the transparent tool list.

Read any trust findings locally. Symlinks and incomplete scans can withhold a skill. Review the actual files; do not silently enable a trust override.

Dense says enabled, but I want lexical only

In 0.0.4, dense status probes backend execution. A READY result is not a configuration toggle or a model-warmup result. To keep the router lexical, set embeddings to "off" and restart the client connection. This is particularly important in a source workspace or an existing setup with the runtime already installed.

Conversely, dense enable does not change an "off" config or prove a model is warm. A missing or unusable runtime keeps routing lexical. See the retrieval guide.

Repair reports a missing runtime after npm succeeds

Version 0.0.3 could retain an earlier missing-package lookup inside the installing Node process. After npm restored a removed runtime manifest, that stale lookup could produce a false repair failure even though a fresh dense status process reported READY.

Use the pinned 0.0.4 commands in this guide. The post-install check now resolves and probes the owned runtime in a fresh process. A genuine missing or unusable backend still reports failure and preserves lexical routing; do not clear unrelated state or weaken file-safety checks.

Dense on Alpine or musl

The 0.0.2 native runtime could report ON before failing with ERR_DLOPEN_FAILED and a missing glibc loader. Upgrade to the pinned 0.0.4 commands in these guides: the local WASM worker handles the verified stock-Alpine x64 and ARM64 configurations without adding glibc compatibility packages.

Check for READY (WASM CPU fallback; model readiness is not checked). The model still needs its separately authorized first-use download, or a complete existing cache. If the backend is unavailable, stay lexical and inspect the reported error; do not copy binaries or disable safeguards. ARMv7 dense support has not been established by these checks.

Dense on Intel macOS

The verified ONNX Runtime 1.24.3 package has a native Apple Silicon binding but no darwin/x64 binding. Roster 0.0.4 uses the local WASM worker on the tested Intel Mac configurations instead of treating installed package files as successful inference.

On Apple Silicon, check node -p process.arch: x64 Node takes the x64 path, while a compatible ARM64 Node can use the native backend. Use the appropriate Node installation rather than copying binaries between architectures. You can always keep embeddings set to "off" if you prefer lexical-only operation.

Eject refuses or was interrupted

Pause client activity and read the reported conflict. Eject may be protecting changed dedicated config bytes, a moved symlink, a corrupt backup, or incomplete recovery data.

Re-run the same scoped eject to resume an interrupted operation. Preserve the backup and journal. --force is a deliberate pristine-byte overwrite choice, not a routine fix and not a bypass for integrity checks.

Still stuck? Open an issue in the repository with the product revision, operating system, Node version, command, and a sanitized error. Do not upload your state directory.