Troubleshooting

This guide aims to help you debug issues with your Turborepo builds and configuration.

My dependency isn't being built correctly

Are you properly bundling and transpiling the dependency before building the application?
- For example, libraries like tsc, tsup, esbuild, babel, and swc will convert newer JavaScript features back to “pure” JavaScript.
- If you are using Next.js, you might be using next-transpile-modules. Ensure you add the name of the dependency inside next.config.js (example).
Have you listed files in the dependency's package.json to point to the correct files?

Did you specify types or typing inside the dependency's package.json to point to the .d.ts file?
Have you altered or set custom tsconfig.json paths?
- Do they have the correct folder structure for your application?
- Are they properly configured for the meta framework, bundler, or transpilation tool?

Is any source code being generated during the build that isn't checked into git?
- This would change the fingerprint Turborepo uses to store build outputs.
Are cache outputs correctly specified in your Turborepo pipeline?
- Pipeline settings are not inherited or merged, so they need to be re-specified in workspace-specific tasks (e.g. web#build does not inherit pipeline settings from build).
Are relevant inlined environment variables accounted for?
- To verify, run turbo in verbose mode by adding -vvv to turbo run <task> and look at which environment variables are included in the hashes.

Are cache outputs properly specified in your Turborepo pipeline?
- Pipeline settings are not inherited or merged, so they need to be re-specified in workspace-specific tasks (e.g. web#build does not inherit pipeline settings from build).

Are relevant inlined environment variables accounted for?
- To verify, run turbo in verbose mode by adding -vvv to turbo run <task> and look at which environment variables are included in the hashes.

Last updated on June 5, 2025