All Collections
Components in Zeplin
Storybook Integration
Troubleshooting tips for Storybook Integration
Troubleshooting tips for Storybook Integration

List of common issues or questions you might have with Storybook Integration

Fatih avatar
Written by Fatih
Updated over a week ago

Here are a few issues and questions you might have while setting up and working with the Storybook Integration and their answers.

Setting up the integration

If you see the “Looks like there’s a network error.” message while setting up your integration, here are the 5 possible reasons:

1. Your Storybook instance might not be running.

2. Zeplin can’t access story previews. You might need to enable embedding for your Storybook instance or use HTTPS.

  • Zeplin can’t access story previews if embedding Storybook isn’t enabled by unsetting the X-Frame-Options header.

    As Zeplin is embedding your Storybook previews in an iframe, it requires the X-Frame-Options header to be unset (allow all domains). You can learn more about the header here.

  • Zeplin can’t access story previews if your Storybook instance isn’t using HTTPS.

    Due to browser restrictions, Zeplin can only embed content that supports HTTPS (this is because Zeplin itself is served over HTTPS). This becomes an issue if your Storybook instance doesn't have an SSL certificate and HTTPS support.

    Don't panic! There is plenty of information online on how to add HTTPS support to your Storybook server, and you can get free SSL certificates from

    If you're serving your instance through a localhost, this shouldn't be an issue.

3. Zeplin can’t access story previews on Safari if your Storybook instance is served through a local host. Try using a different browser or the Zeplin desktop app to set up the integration and see previews.

Due to Safari's restrictions, Zeplin can't get the story data if you use a localhost URL.

4. Zeplin can't access your password protected Storybook instance.

This one is only applicable to the desktop app. For now, you can try setting up the integration on the Web app by logging into your instance in another tab.

5. If you're setting up the integration using the Web app, you need to install Zeplin's Storybook addon.

To install the addon, you can run the following command on your Storybook instance:

npm i --save-dev storybook-zeplin

If you already have the addon installed on your instance, you can run the following command to update it:

npm i --save-dev storybook-zeplin@latest


My Storybook instance is private. What should I expect?

Anyone who wants to see how the integration works or link stories with components will need access to the website where your Storybook is hosted. If it's an internal website, it may only work for people when they are within your company's network.

If your team members access Zeplin from a public computer, they will not be able to see anything. To fix this, you can make your Storybook website publicly accessible.

I'm serving my Storybook instance through a localhost URL. What should I expect?

Stories won't be available for your team members if you use a localhost URL. We suggest moving your instance to somewhere accessible if you're planning to collaborate with your team.

I have a composition set up in my Storybook instance. What should I expect?

Due to technical limitations, the Composition structure is sadly not supported at the moment. For now, only the stories under the main instance will be available.

I've used CLI before to connect to a Storybook instance. What should I expect?

If you've used CLI before, your links for these components will also be available in Zeplin. You can also continue using CLI—adding components using CLI will reflect them in Zeplin’s Storybook Integration.

💁‍♀️ If you have any other issues or questions, you can ping us at anytime from

Related articles

Did this answer your question?