Skip to main content

Debugging

When a command fails, match the symptom below and apply the fix. Most first-run problems are one of these. If none match, jump to Still stuck?.

pnpm is not recognized / pnpm: command not found​

The React frontend uses pnpm (pnpm install, pnpm dev, pnpm build). pnpm doesn't ship with Node, so you install it once. The scaffold pins a pnpm version (pnpm@10.11.0), so the preferred way is Corepack — it's bundled with Node and honours that pinned version:

corepack enable pnpm

If Corepack isn't available on your setup, install pnpm globally with npm instead:

npm install -g pnpm

Confirm it's on your PATH:

pnpm --version

uv not found (backend dependencies were skipped)​

The Rystad Flask backend installs its Python dependencies with uv. If scaffolding printed a warning like Skipped backend deps: 'uv' not found, install uv:

pip install uv

uv needs Python 3 on your PATH. If pip points at Python 2, use pip3 install uv instead.

Then install the backend dependencies from the project's backend/ folder:

cd my-dash/backend
uv sync

uv sync fails: dynamix_wrapper / python_logger not found​

If uv sync stops with something like No solution found … dynamix-wrapper was not found in the package registry, uv reached PyPI but not the private Rystad Artifacts feed where dynamix_wrapper and python_logger live. The generated backend/pyproject.toml already points uv at that feed (under [tool.uv]), so this almost always means you aren't authenticated to it yet.

Set up feed auth once, then re-run the sync:

uv tool install keyring --with artifacts-keyring  # keyring CLI on PATH (uv runs the executable)
az login                                          # Azure sign-in
cd my-dash/backend
uv sync

uv does not read pip.conf, so configuring the feed for pip alone isn't enough — the feed is declared in pyproject.toml for uv.

uv sync fails: 401 Unauthorized on the Rystad feed​

If the resolver error ends with a hint like An index URL (…/pypi/simple/) could not be queried due to a lack of valid authentication credentials (401 Unauthorized), uv reached the feed but couldn't authenticate. Two uv-specific gotchas cause this even right after az login:

  1. The keyring CLI isn't on your PATH. Unlike pip, uv shells out to the keyring executable, and a plain pip install artifacts-keyring often lands where uv can't see it. Install it as a uv tool instead:

    uv tool install keyring --with artifacts-keyring

  2. The index URL is missing its username. uv only consults keyring when the URL carries one, and for Azure Artifacts it must be VssSessionToken. The generated pyproject.toml bakes it in (https://VssSessionToken@pkgs.dev.azure.com/…); if you edited that file, put the username back.

Prefer not to use keyring? Add the feed to a user-level ~/.netrc and uv will authenticate with it directly:

machine pkgs.dev.azure.com
login RE-Technology
password PASTE_YOUR_PAT

401 Unauthorized on npx, npm install, or MCP start​

Your machine can't authenticate to the private @rystad npm feed — the most common first-run failure. Configure your Azure DevOps token in your user-level ~/.npmrc; the full walkthrough is in First-time setup (and PREREQUISITES.md at the repo root).

Verify it's fixed:

npm view @rystad/create-rystad-dashboard version

A version number instead of 401 means you're authenticated.

404 Not Found — 'create-rystad-dashboard@*' is not in this registry​

You dropped the @rystad/ scope. The package isn't on public npm, so always use the scoped name:

npx @rystad/create-rystad-dashboard my-dash --dashboard-id 300

The stack won't start with docker compose up​

create-rystad-dashboard only auto-starts the stack once the local prerequisites are ready. If it printed the one-time steps instead of booting, work through the generated RUN_LOCAL.md and confirm that:

  • Docker is running — start Docker Desktop and wait until it reports ready.
  • The registry images are pulled — run az login && az acr login -n reapregistry.
  • Your aspose.license.key file is at the project root — see RUN_LOCAL.md.
  • .env is filled in — copy the template and set the values it lists.

Then run docker compose up again from the project folder.

node --version is below 18​

The CLIs require Node.js 18 or newer (the latest LTS, 20 or 22, is recommended). Upgrade from nodejs.org — or run nvm install 20 if you use nvm — then re-run your command. Check with:

node --version

Still stuck?​

  • Ask your AI assistant to re-check against the MCP servers and re-run the verify step — most "something looks wrong" cases resolve here (see the FAQ's Something looks wrong answer).
  • If your assistant suggests disabling a guardrail to move faster, don't — that's a red flag (see Safe prompting).
  • Still blocked? Reach out to your team's platform channel with the exact command you ran and the full error text.