Why does my Storybook on Vercel show 404 NOT_FOUND?

By Ohad Krispin, founder of VibeRaven · LinkedIn

A Storybook on Vercel shows 404 NOT_FOUND when Vercel serves a folder that has no Storybook files in it. Two causes are common. The project is the app's project, so Vercel detected Next.js or Vite and built the app, not Storybook: Vercel marks Storybook detection as weak, because many apps only have it as a devDependency. Or the Output Directory does not match what Storybook wrote, and Vercel serves an empty folder where every path 404s. Storybook writes ./storybook-static unless you pass -o. Create a second Vercel project for the same repo, set its Framework Preset to Storybook (build storybook build, output storybook-static), and redeploy.

What the 404 means

Vercel documents the error as "404 NOT_FOUND: Not Found", raised when a requested resource could not be found. Its 404 guide says that when the Output Directory setting does not match where the build tool drops files, Vercel serves an empty folder and every path 404s. It adds that the Output tab on a deployment shows exactly which files the build produced, and that when expected files are not listed there, the problem is build configuration, not routing.

404
NOT_FOUND:
Not Found

Why a Storybook in an app repo builds the app instead

A Vercel project has one Framework Preset, used for all its deployments. Vercel's framework list (packages/frameworks/src/frameworks.ts) has a Storybook entry with a comment that Storybook is a devDependency of many apps that deploy something else, so detection is "weak". In a repo whose package.json lists Next.js and Storybook, a project made for the app builds the app with the Next.js settings. The Storybook preset in the same file sets the build command to storybook build, ignoring the package.json script, and the output directory to storybook-static.

On the Storybook side, the CLI source (core/src/cli/build.ts) uses ./storybook-static when no output directory is given, and the build logs "Output directory:" with the resolved path. A custom -o folder moves the files away from where Vercel looks.

Project A (app):        Framework Preset Next.js
Project B (Storybook):  Framework Preset Storybook   build storybook build   output storybook-static

How do I set up the Storybook project?

Vercel's Storybook guide sets buildCommand to npm run build-storybook and outputDirectory to ./storybook-static in a vercel.json, with framework set to null so the zero-config detection does not pick the app's framework. If the same folder also deploys the app, a vercel.json there can change the build of the app too, so set these as Override values in the second project's Build and Deployment settings instead. Vercel says an Override applies to all deployments of that project and takes effect on the next deployment.

{
  "framework": null,
  "buildCommand": "npm run build-storybook",
  "outputDirectory": "./storybook-static"
}

Checklist

How to fix it, then check the fix

Build Storybook on your machine and read the last log line:

npm run build-storybook
# look for: Output directory: .../storybook-static

02In Vercel, add a new project from the same repository for Storybook, with the Root Directory set to the folder that holds the .storybook folder.
03In that project's Build and Deployment settings, choose the Storybook Framework Preset, or override the Build Command to npm run build-storybook and the Output Directory to storybook-static. Keep the app in its own project.
04If you build with a custom -o folder, put the same folder in the Output Directory field.
05Redeploy, open the deployment's Output tab and check that the Storybook files, including index.json, are listed, then open the deployment URL.

Sources

Official docs behind this checklist

Browse all launch guides · Read resources · How to make and check your next change

FAQ

FAQ for builders before launch

Do I need a second Vercel project for Storybook?

Usually yes. A project has one Framework Preset for all its deployments, and Vercel detects the app first. A second project from the same repository lets the app and Storybook each keep their own build command and output directory.

Does the Storybook preset run my build-storybook script?

No. In Vercel's framework definition the build command is storybook build with the package.json script ignored. If your script adds options such as -o or --test, override the Build Command in the project settings.

Why does it work with npm run build-storybook locally and 404 after deploy?

Locally you serve the folder Storybook just wrote. On Vercel, only the contents of the Output Directory are served, so a setting that points at another folder serves nothing. Compare the path from the build log with the Output Directory field.