Backstage yarn workspaces build fails in CI

A Backstage app is a yarn workspaces monorepo (packages/app, packages/backend, plugins/*). Builds fail when a workspace references another that has not been built, or when install did not link the workspaces together.

What this error means

The build stops with "Couldn't find package \"@internal/plugin-x\" ... on the \"npm\" registry" or a TypeScript error importing a sibling workspace that was never compiled.

error Couldn't find package "@internal/plugin-example@^0.1.0" required by
"backend@0.0.0" on the "npm" registry.
error An unexpected error occurred: "https://registry.yarnpkg.com/@internal%2fplugin-example: Not found".

Common causes

Install ran without workspace linking

Running install inside a single package, or with a flag that skips workspace resolution, means yarn looks up the internal package on the public registry instead of linking the local one.

Builds run in the wrong order

A package that depends on a sibling is built before the sibling, so its compiled output is missing.

How to fix it

Install and build from the repo root

1. Run yarn install at the repository root so all workspaces link.
2. Compile types across the monorepo with yarn tsc.
3. Build backend and app through the root scripts.

yarn install --immutable
yarn tsc:full
yarn build:all

Build a single workspace with the right dependencies

When targeting one package, include the packages it depends on so their output exists first.

yarn workspace backend build

How to prevent it

• Run install and build from the monorepo root, not inside one package.
• Use the root build scripts so workspace build order is honored.
• Reference internal packages by their workspace name so yarn links them.

Related guides