Troubleshooting

The most common things that go sideways in the first hour. If you hit something that isn’t listed, open an issue — we add to this page from real reports.

”command not found: ttsc”

You haven’t installed ttsc locally, or you’re trying to call it as a global binary.


npm install -D ttsc @typescript/native-preview
npx ttsc --version

Always go through npx (or your package.json scripts). ttsc is not a global install — it’s per-project, so each project pins its own version.

”Cannot find module ‘@typescript/native-preview’”

Same root cause — @typescript/native-preview is a peer dependency, not bundled. Add it to your devDependencies.


npm install -D @typescript/native-preview

The first build hangs / takes a long time.

On a fresh install, ttsc compiles its plugin binaries into a cache the first time you run it. On a typical machine this is under 10 seconds per plugin, but it only happens once per node_modules. If you want to pre-warm:


npx ttsc prepare

You can drop the cache with ttsc clean.

”plugin ‘X’ not found”

Your tsconfig.json mentions a plugin that isn’t installed:


{
  "compilerOptions": {
    "plugins": [
      { "transform": "@ttsc/lint" }   // → require this in package.json
    ]
  }
}

Install the plugin package (npm install -D @ttsc/lint) or remove the entry.

I added `@ttsc/lint` but I see no lint errors.

Two checks:

Is the plugin actually wired in? compilerOptions.plugins should include { "transform": "@ttsc/lint" }.

Is there a lint.config.ts? Without one, the rule set is empty. Minimum file:


import type { TtscLintConfig } from "@ttsc/lint";
 
export default {
  rules: {
    "no-var": "error",
    "prefer-const": "error",
  },
} satisfies TtscLintConfig;

“Banner config file not found”

@ttsc/banner requires banner.config.ts (or an inline text option in tsconfig.json). Detail: Banners.

VSCode doesn’t show lint diagnostics live.

You need the VSCode extension. The vanilla TypeScript language service doesn’t know about plugins; ttscserver is what merges plugin diagnostics into the editor stream. The extension is not yet on Marketplace — build packages/vscode-ttsc from the workspace and code --install-extension the produced .vsix.

After install, look at the Output → ttsc panel for the server log if diagnostics still don’t appear.

”Type ‘X’ is not assignable” only after `ttsc fix`.

ttsc fix applies all autofixes (lint + format), then re-checks. If the autofixed code still has a real type error, the command exits non-zero with the file rewritten. Investigate the remaining error — it was almost certainly there before, just shadowed by a lint violation.

The bundler integration is silent — no plugin output.

@ttsc/unplugin reads your tsconfig.json. If the bundler is being invoked from a different cwd, point it explicitly:


ttsc({ cwd: __dirname, project: "tsconfig.build.json" });

Watch mode keeps re-checking the same file.

This usually means another tool is rewriting the same file. Common culprits: prettier --write on save (now redundant — ttsc format does this), an active formatter in your editor, or a parallel ttsc fix running in another terminal.

Something else

GitHub Issues
Discord
Plugin authors: pitfalls — failures specific to writing plugins.