Common development troubleshooting checklist

Here are common issues related to codebase integrations. Use this troubleshooting checklist when you encounter an issue.

General troubleshooting

Try from a new create-plasmic-app

This is the most common recommendation for various issues. Much of the time, there is something happening that’s specific to the codebase that Plasmic is being integrated with, and this will help you narrow down to whether that’s the case. The issue may come from a code component, from code surrounding the Plasmic component, from data fetching differences in your production environment, etc.

If the problem is specific to your codebase, then you can compare to search for differences. You can also start incrementally making either side more similar to the other to see at what point the issue starts getting introduce.

You can also try deploying to *.plasmic.run. This is a convenient option in the Publish modal, but it also gives you less visibility into what’s happening under the hood.

Try opening your project with ?debug=true

This disables custom code components from your app host. Instances of code components render as null instead and pass through their slot contents.

This can help you track down whether an issue is specific to your code components.

This mode also disables auto-saving (but will still save if you press cmd+S).

Plasmic project issues

Narrow down the problem

For issues that are coming in a specific part of your project, try narrowing down the problem further to determine the problematic element(s).

Continually try removing sets of elements until the issue goes away. (Or try making multiple copies of a problematic page, removing differing amounts of content on each.)

You can also try reproducing your issue outside of your Plasmic project altogether, from a brand new Plasmic project.

Hydration errors

A common issue is illegal nesting of HTML. For example:

• Nesting links within links
• Nesting divs within paragraphs
• Nesting buttons within links
• Etc.

When doing SSR/SSG (e.g. using Next.js), HTML is sent first, then JS hydrates it, and the DOM structures should match. But with illegal nestings, the browser will actually try to “unnest” these in the HTML response, and then the JS hydrated structure won’t match. Learn more.

Note that sometimes this nesting can happen across different component boundaries.

To track these down, open Chrome Devtools console and query your page for these. Common nestings are:

document.querySelector('a a');
document.querySelector('p div');

You can also try to narrow down the problem.

Seeing whitespace on the right

This is due to some element on the page that has a fixed width or fixed min-width that is too wide, causing the entire viewport (typically on mobile devices) extend to the right.

You can either:

• Use Chrome Devtools’s inspector to sweep your mouse down the whitespace on the page until it highlights some element that is “sticking out”.
• Incrementally try deleting parts of your page until the issue is gone (usually you can see it in preview mode). Narrow down the problem.

Integrating Plasmic

Update your Plasmic packages

We try to maintain backward compatibility with published Plasmic packages. However, on occasion, specific scenarios may not be covered by our automated tests.

It’s generally good to stay up-to-date. Besides minimizing issues, this can also help ensure you receive the latest performance and new features.

Incompatible Plasmic package versions

@plasmicapp packages can depend on each other. Each package always has an exact version of its @plasmicapp dependencies. This is because we want to ensure that all packages are always in sync, and that we don’t end up with a mismatched set of packages.

Packages like @plasmicapp/host must also be deduped, since functionality such as registerComponent make use of globals and side effects, so with multiple versions you could end up using the wrong “instance” of this package. Additionally, types can be tightly coupled across multiple packages.

Unfortunately, npm and yarn make it easy for you to end up with mismatched versions and duplicate versions of packages. Use the npm list command to ensure that you have unique deduped versions of packages. Furthermore, issues can be “sticky,” since npm/yarn are stateful. At times, you may need to rely on npm dedupe, or removing and reinstalling Plasmic packages (including @plasmicpkgs packages), resetting package-lock.json/yarn.lock, in order to unwedge npm/yarn.

Examples:

• You may have a mismatched version of @plasmicapp/host when there’s already one included @plasmicapp/loader-nextjs.
• You tried upgrading @plasmicapp/loader-nextjs, but npm/yarn did not end up upgrading @plasmicapp/host.

@plasmicpkgs (the built-in code component packages) have @plasmicapp packages as peer dependencies, and these specify ranges rather than exact versions—this is to offer some flexibility for developers to use the core package versions they need, while still using @plasmicpkgs.

Importing from the wrong package

When you have multiple Plasmic packages installed, make sure you are importing from the correct one.

You may be importing DataProvider from @plasmicapp/host instead of @plasmicapp/loader-nextjs.

Not picking up changed invocation of initPlasmicLoader

For some frameworks, like Next.js, initPlasmicLoader performs some file level caching in order to speed up development iteration.

You’ll need to stop and restart your server if you change the initPlasmicLoader flags, due to caching that the Plasmic SDK performs.

Codegen

Element type is invalid: got undefined

If you are using codegen and get this React error:

Unhandled Runtime Error Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it’s defined in, or you might have mixed up default and named imports.

This is usually due to missing or incorrect import paths in your custom code component registration.

Plasmic CLI

Authentication errors from the CLI or Loader

The easiest way to get your system authenticated with Plasmic is to use our CLI with the following command:

npx -p @plasmicapp/cli plasmic auth

However on rare occasion, this process may also fail. To debug this situation, check for the existence of this file in your home directory: ~/.plasmic.auth.

If it does not exist, you can create the file manually like this:

{
  "host": "https://studio.plasmic.app",
  "user": "EMAIL_HERE",
  "token": "TOKEN_HERE"
}

Make sure that the email you insert here is the one that you used to sign up on the Plasmic Studio. You can get your access token from your settings. This file is all you need to authenticate your system.

Have feedback on this page? Let us know on our forum.