Running Turborepo?

Turborepo remote cache missing every build? We ship it properly.

Turborepo earns its keep when the cache hit rate is high and the task graph matches what your packages actually do. If neither is true, the tool has made CI slower, not faster. We work through the inputs, outputs and remote cache until the numbers go the right way.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

turbo-run.log

still failing

What it is

Turborepo at a glance

Turborepo is a build system for JavaScript and TypeScript monorepos, originally created by Jared Palmer and acquired by Vercel in late 2021. Written in Go for the hot paths, it treats tasks as a directed graph across packages and caches each task output by a hash of its inputs.

The runner reads a turbo.json that describes which tasks depend on which, which files feed each task, and where the outputs land. On top of that it offers a remote cache so that one engineer's build artifacts can be reused by the next engineer or the next CI job, which is the feature most teams buy it for.

Type
Monorepo task runner and build cache
First released
2021 open source
License
MPL 2.0 for the core, Vercel remote cache is a paid service
Maintained by
Vercel, Inc.
Typically used for
JavaScript and TypeScript monorepos, task orchestration, remote caching of builds and tests

The honest version

Turborepo pros and cons

No technology is all upside. This is where Turborepo earns its place and where it tends to cause trouble.

Where Turborepo is strong

  • Cache hits turn slow pipelines into fast onesWhen inputs have not changed, the task is replayed from cache in seconds, so a developer pulling main does not pay the full build cost again.
  • Remote cache sharing across the teamBuilds produced on one machine, including CI, can be reused on another, which cuts the second person's typecheck or test run to near zero.
  • Task graph resolved automaticallyDependencies between packages are read from the workspace, so you declare task relationships rather than hand editing a makefile every time a package moves.
  • Simple mental modelA turbo.json with a handful of tasks and an outputs list covers most projects. There is no plugin system to learn before the first run.
  • Works with any package managerpnpm, yarn and npm workspaces are all supported, so you can add Turborepo to an existing monorepo without changing how dependencies are installed.
  • Good CI integrationLogs are grouped per package, failing tasks are easy to spot, and the summary shows exactly which packages were rebuilt versus pulled from cache.

Where Turborepo bites

  • Remote cache signature issues are easy to hitSigned cache requires a matching secret across local and CI, and when they drift you get a quiet fallback to local cache rather than a loud error at the top of the run.
  • Inputs are only as accurate as you declareIf you miss a config file or a generated type, Turborepo hashes an incomplete input set and serves a stale cache. Finding that bug can take days.
  • Hash churn kills the cache hit rateA package that includes timestamps, build IDs or absolute paths in its outputs will invalidate every downstream package on every run, and the cache stops helping.
  • Remote cache is Vercel hosted by defaultRunning your own cache server is possible but relatively niche, so most teams pay Vercel or lose the feature on CI runners that cannot reach the internet freely.
  • Error messages are bluntWhen a task graph cannot be resolved or a hash input is missing, the message tells you something is wrong without pointing at the specific file.
  • Overlap with Nx, Bazel and othersTurborepo covers the common cases well, but once you need distributed execution, custom executors or non JavaScript targets, the tool starts looking small.

Sound familiar?

Common Turborepo problems we fix

The Turborepo problems that bring people to us, and what you have once each one is fixed.

failed to verify remote cache signature

Remote cache is quietly missing

The signing secret on CI does not match the one developers use locally, so every CI build fetches nothing and the team concludes Turborepo is broken rather than misconfigured.

Cache hits where they should be

task hash changed: inputs outside package

Hashes churn on every commit

A task reads a root level file that was never declared as an input, so every unrelated commit invalidates the cache. We walk the inputs list against what the task really touches.

Hashes stable, cache sticks

Missing `outputs` field in task `build`

Builds are cached without their outputs

Turbo stores the log but not the dist folder, so a cache hit saves nothing because the next step still has to rebuild. A correct outputs glob fixes it immediately.

Artifacts restored from cache

package depends on package not in workspace

Workspace graph is wrong

A package.json dependency refers to a path that is not a workspace member, or a workspace protocol was never enabled. Turborepo refuses to resolve the graph.

Workspace graph clean

Cached: 0 cached, 24 total

Cache hit rate is zero

Either no remote cache is wired up, or the hash inputs include something that changes every run. We profile a single task and work out which is the real cause.

Hit rate climbs to where it should be

FULL_TURBO: run is partial

Full turbo mode never activates

A single task without outputs or with non deterministic inputs keeps the whole run from being fully cached. Finding that one task often cuts CI by half.

Full turbo on every main build

could not find pnpm-lock.yaml at root

Package manager detection fails

The lockfile is in a subdirectory, or the root packageManager field is missing. Turbo needs both to locate the workspace properly.

Lockfile and root aligned

task exited with code 1 after 00m02.141s

One package breaks the whole pipeline

A single failing task halts dependents and leaves the build half done. Sometimes the task is genuinely broken, sometimes it needs a conditional or a different scope.

Pipeline scoped and isolated

What we do

Turborepo help, from cache fixes to pipeline design

Call us for one slow build, or let us rework the whole monorepo pipeline.

Rescue
Remote cache missing, pipelines slower than before, or hashes that refuse to stabilise. We find the cause and show the before and after numbers.
Remote cache setup
Vercel remote cache or a self hosted equivalent wired up correctly, with signed requests, matching tokens, and validation that CI is actually reading from it.
Task graph design
Inputs, outputs, dependsOn and env declared against what your packages really do, so hashes mean something and full turbo mode becomes reachable.
Monorepo migrations
Moving onto Turborepo from Lerna, raw pnpm scripts, or Nx done in one measured pass with the old command still working until the new one is proven.
CI pipeline tuning
Sharded test runs, affected scope filters, and parallel jobs set up against Turbo's graph so pull requests do not wait on unrelated packages.
Managed Tech
Monthly reviews of cache hit rate, pipeline runtime, task ownership and upgrade status, plus a team on call when the build suddenly loses its cache.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Turborepo alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Turborepo questions

Something else? Call+1 737 727 7327

Why does our remote cache hit rate stay at zero?

Three usual causes: the TURBO_TOKEN is missing on CI, the team ID does not match the one used locally, or the hash includes a file that changes on every run. The run summary shows which it is. We confirm the token is visible in the environment, that signed verification succeeds, and that the inputs list excludes files like timestamps or generated build IDs.

Should we pick Turborepo or Nx for our monorepo?

If the repo is pure JavaScript or TypeScript and you want a small configuration surface, Turborepo is the lighter choice. If you need generators, Angular support, custom executors or non JS targets, Nx tends to pay off. We benchmark both against a copy of your real pipeline before recommending one.

Why do our pipeline hashes keep changing?

Usually a task is reading a file outside its declared inputs, or an output includes something non deterministic like a timestamp. The task hash summary in verbose mode shows every file that feeds the hash, which is how we track the culprit down.

Can we run our own remote cache instead of paying Vercel?

Yes. Several open source servers implement the Turbo remote cache protocol, and we have deployed them inside AWS, GCP and private networks. It is more work than clicking the Vercel button, but it is perfectly workable once set up.

How do we move from Lerna or raw npm scripts to Turborepo?

We add turbo.json alongside the existing scripts, wire up one or two tasks, prove the cache works, and then move the rest over package by package. Lerna and npm scripts keep running throughout, so nothing stops working during the migration.

How much does Turborepo help cost?

Free estimate. Send over your turbo.json and a recent CI run log, and we come back with a quote and a rough plan before we touch anything.

Free estimate

Turborepo not making builds faster?

Tell us what you're running and what's going wrong. A person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.