---
title: Troubleshooting
description: This guide aims to help you debug issues with your Turborepo builds and configuration.
---

# Troubleshooting

As with most tools, it can be frustrating to understand why Turborepo
is not working the way you expect. This page covers some tools to debug when
using the `turbo` CLI and some common problems you may encounter.

## Enable Verbose Logs

THe best debugging tool we have as developers are logs. You can turn up the log
level with the [`--verbosity`][1] flag. Combined with [building from
source][3], this can be a powerful and flexible way to see what's going on under
the hood.

## Check your Configuration

### Task Configuration

You can [get started][7] with Turborepo with minimal configuration -- that's one
of the things people love about Turborepo! But when you omit configuration,
Turborepo internally falls back to smart defaults. Additionally, when using
[Workspace Configurations][d-config-workspaces] in a monorepo, it can be
confusing to understand how Turborepo interpreted your `turbo.json`. You can use
the `--dry` or `--dry=json` to get a "resolved" task configuration for any task.
For example:

```bash
turbo run build --dry=json
```

Look for a `resolvedTaskConfiguration` key in the output.

### User Config

When you link your repository to Vercel, Turborepo stores configuration in two places:

- your Vercel team information is stored in `.turbo/config.json`. You can
  inspect this file to see what else might be in there!
- an authentication token is stored in
  `~/Library/Application\ Support/turborepo/config.json`.

## Inspect the Cache

When turborepo runs a task that has configured `outputs`, it caches those
outputs, along with the logs from that task in the `node_modules/.cache/turbo/`.
These artifacts are compressed with `tar`, but you can uncompress and see what's
in them.

## Build from Source

One of the advantages of JavaScript codebases are that you can open up
`node_modules/` and edit the code you're running inline. This is not possible
with `turbo`, because the runnable code is a compiled binary and you cannot edit
it inline. But because the codebase is Open Source, you can always get
the source code, modify it, and build it locally. The bulk of this
documentation is available in the [Contributing Guide][4], but you can use those
directions even if you aren't planning to make a contribution.

1. Clone the git repo from [`vercel/turbo`][source]
1. `cd cli`
1. Make any changes (for example, add more logging)
1. Run `make`
1. From _your_ project, use `/:path/:to/:turbo/target/debug/turbo` instead of global
   turbo or the version of `turbo` installed in your project.

## Common Pitfalls

### The `.turbo` directory

One of the [core concepts][2] behind Turbo is that when a declared input
changes, the cached outputs for that task are invalidated. As part of running any task,
Turborepo creates the following directories:

- A `.turbo` at the root of your repo
- A `.turbo` directory in each workspace if your project is a monorepo (e.g. `apps/my-app/.turbo/`)
- A `turbo` directory in `node_modules/.cache`

Because the first two directories are not git-ignored by default, you may see an
issue where you run the same task twice and get a cache missing, even though you
didn't change anything, because the generated `.turbo` directories are getting included as
the task _inputs_, and invalidating cache. To avoid this problem, add `.turbo` to your
`.gitignore` file. Alternatively, you can also limit your [`inputs` configuration][r-inputs-config]
so that `.turbo` is not included in the cache inputs.

## Common Questions

### I'm not seeing any cache hits

- 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][d-config-outputs] in your Turborepo [pipeline][d-def-pipeline]?

  Pipeline settings are not inherited or merged, so they need to be
  re-specified in [workspace-specific tasks][d-workspace-tasks] (e.g. `web#build` does
  **not** inherit pipeline settings from `build`).

- [Are relevant inlined environment variables accounted for?][12]

  [Enable verbose mode][5] to see which environment variables are included in the hashes.

### I'm seeing cache hits, but my build is broken

- Are [cache outputs properly specified][d-config-outputs] in your Turborepo [pipeline][d-def-pipeline]?

  Pipeline settings are not inherited or merged, so they need to be
  re-specified in [workspace-specific tasks][d-workspace-tasks] (e.g. `web#build` does
  **not** inherit pipeline settings from `build`).

### My build is caching the wrong environment variables

- [Are relevant inlined environment variables accounted for?][12]

  [Enable verbose mode][5] to see which environment variables are included in the hashes.

## Common Monorepo Questions

### 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 `transpilePackages`. Ensure you
  add the name of the dependency inside `next.config.js` ([example][17]).

- Have you listed `files` in the dependency's `package.json` to point to the correct files?

### My types are not being found

- 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?

[1]: /repo/docs/reference/command-line-reference#verbosity
[2]: /repo/docs/core-concepts/caching
[3]: #build-from-source
[4]: https://github.com/vercel/turbo/blob/main/CONTRIBUTING.md
[5]: #enable-verbose-logs
[7]: /repo/docs/getting-started
[9]: /repo/docs/reference/command-line-reference#turbo-link
[12]: /repo/docs/core-concepts/caching#altering-caching-based-on-environment-variables
[17]: https://github.com/vercel/turbo/blob/main/examples/basic/apps/docs/next.config.js#L1
[d-workspace-tasks]: /repo/docs/core-concepts/monorepos/running-tasks#specific-workspace-tasks
[d-config-workspaces]: /repo/docs/core-concepts/monorepos/configuring-workspaces
[d-config-outputs]: /repo/docs/core-concepts/caching#configuring-cache-outputs
[d-def-pipeline]: /repo/docs/core-concepts/monorepos/running-tasks#defining-a-pipeline
[source]: https://github.com/vercel/turbo
[r-inputs-config]: /repo/docs/reference/configuration#inputs
