Storybook composition ref unreachable in CI

Storybook composition embeds other Storybooks via the refs field in main.js. In CI, if a referenced URL is private, offline, or not yet deployed, the ref cannot load, and a build that validates refs or a test-runner reading the index can fail.

What this error means

The build or runner logs that a ref could not be loaded, or the composed Storybook shows an unreachable ref, naming the URL from refs.

Could not fetch composed Storybook at ref "design-system":
https://storybook.internal.example.com (request failed)

Common causes

The referenced Storybook is not reachable from CI

The ref URL is internal or behind auth, so the CI runner cannot fetch its index.json.

The composed Storybook is not deployed yet

The ref points at a build that has not been published, so the URL 404s during CI.

How to fix it

Make refs reachable or conditional in CI

1. Confirm the ref URL responds from the runner's network.
2. For private refs, provide the reachable URL or credentials.
3. Skip or stub refs that are not needed for the CI build.

// .storybook/main.ts
export default {
  refs: (config, { configType }) =>
    configType === 'PRODUCTION'
      ? { 'design-system': { title: 'DS', url: 'https://ds.example.com' } }
      : {},
};

Publish the referenced Storybook first

Order the pipeline so the composed Storybook is deployed before builds that reference it.

How to prevent it

• Ensure ref URLs are reachable from CI or make them conditional.
• Deploy referenced Storybooks before dependent builds.
• Avoid pointing refs at private hosts CI cannot reach.

Related guides