> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Effect-TS/tsgo/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common problems with effect-tsgo installation, diagnostics, binary patching, and editor integration.

<AccordionGroup>
  <Accordion title="Diagnostics are not showing in my editor">
    Work through each of these checks in order.

    **1. Verify the plugin is configured in `tsconfig.json`**

    Your `tsconfig.json` must include the `@effect/language-service` plugin entry:

    ```jsonc theme={null}
    {
      "compilerOptions": {
        "plugins": [
          {
            "name": "@effect/language-service"
          }
        ]
      }
    }
    ```

    If the `plugins` array is missing or the name is wrong, no diagnostics will appear. Run `npx @effect/tsgo setup` to add it automatically.

    **2. Check that your editor is using effect-tsgo as the TypeScript server**

    The standard built-in TypeScript server bundled with VS Code (or another editor) does not include the Effect Language Service. You must configure your editor to use `effect-tsgo` instead.

    The recommended approach is the `patch` command, which replaces the `@typescript/native-preview` binary. See the [Editor Setup](/editor-setup) guide for per-editor instructions.

    Run the following to find the binary path and use it in your editor config:

    ```bash theme={null}
    npx @effect/tsgo get-exe-path
    ```

    **3. Verify the binary location**

    Run the following command to confirm the binary has been installed:

    ```bash theme={null}
    npx @effect/tsgo get-exe-path
    ```

    This prints the absolute path to the `effect-tsgo` binary for your platform. If it fails or returns an error, run `npx @effect/tsgo patch` to (re-)apply the binary.

    **4. Confirm `@effect/tsgo` is installed in the project**

    ```bash theme={null}
    npm ls @effect/tsgo
    ```

    If it is not listed, install it:

    ```bash theme={null}
    npm install @effect/tsgo
    ```
  </Accordion>

  <Accordion title="Running effect-tsgo alongside tsgo causes duplicate diagnostics">
    Do **not** run both `effect-tsgo` and the official `tsgo` at the same time. Because `effect-tsgo` is a superset of `tsgo`, running both produces duplicate diagnostics and degrades editor performance.

    Configure your editor to use `effect-tsgo` as the **sole** TypeScript language server. Remove any explicit `tsgo` server configuration and replace it with the `effect-tsgo` binary.

    The recommended approach is to run:

    ```bash theme={null}
    npx @effect/tsgo patch
    ```

    This replaces the `@typescript/native-preview` binary that your editor loads, so no additional editor configuration is needed when using the TypeScript Native Preview extension. See the [Editor Setup](/editor-setup) guide for details.
  </Accordion>

  <Accordion title="Binary patching issues">
    **How patching works**

    Running `npx @effect/tsgo patch` replaces the default TypeScript-Go binary with the Effect-patched version. A numbered backup of the original binary is created automatically before each patch operation.

    To restore the original binary:

    ```bash theme={null}
    npx @effect/tsgo unpatch
    ```

    **Too many backup files**

    Each call to `patch` creates a new backup. If you have patched and unpatched many times, more than 100 backup files may accumulate. Clean them up manually from the directory printed by `npx @effect/tsgo get-exe-path`.

    **Platform support**

    Pre-built binaries are available for:

    | Platform | Architecture          |
    | -------- | --------------------- |
    | macOS    | arm64 (Apple Silicon) |
    | macOS    | x64 (Intel)           |
    | Linux    | x64                   |
    | Linux    | arm64                 |
    | Linux    | arm                   |
    | Windows  | x64                   |
    | Windows  | arm64                 |

    If you are on an unsupported platform, the binary install step will fail. Consider using the [Nix flake](/guides/version-pinning#nix-flake) to build from source.
  </Accordion>

  <Accordion title="Breaking changes after upgrading">
    `@effect/tsgo` is in **alpha**. Breaking changes to plugin options, diagnostic names, and behaviour may occur between releases without a major version bump.

    Before upgrading, review the [CHANGELOG](https://github.com/Effect-TS/tsgo/blob/main/_packages/tsgo/CHANGELOG.md) for the releases between your current version and the target version.

    Some features present in the previous TypeScript-based version of the Effect Language Service may be temporarily missing or behave differently — this is expected while the Go-based port is in progress.
  </Accordion>

  <Accordion title="tsc exit code is non-zero due to Effect diagnostics">
    By default, Effect suggestion-level diagnostics do not affect the `tsc` exit code, but warnings and errors do. Use the following plugin options to adjust this behaviour:

    ```jsonc theme={null}
    {
      "compilerOptions": {
        "plugins": [
          {
            "name": "@effect/language-service",
            // Suggestions never affect exit code (default: true)
            "ignoreEffectSuggestionsInTscExitCode": true,
            // Set to true to prevent warnings from failing CI
            "ignoreEffectWarningsInTscExitCode": false,
            // Set to true to prevent errors from failing CI
            "ignoreEffectErrorsInTscExitCode": false
          }
        ]
      }
    }
    ```

    To suppress suggestion diagnostics from `tsc` output entirely (without hiding them from the editor), set:

    ```jsonc theme={null}
    {
      "compilerOptions": {
        "plugins": [
          {
            "name": "@effect/language-service",
            "includeSuggestionsInTsc": false
          }
        ]
      }
    }
    ```

    <Note>
      `ignoreEffectSuggestionsInTscExitCode` defaults to `true`, so suggestions never cause a non-zero exit code out of the box.
    </Note>
  </Accordion>

  <Accordion title="Directive overrides for disabled rules are not taking effect">
    By default, when a diagnostic rule is disabled in `diagnosticSeverity`, the language service skips processing it entirely for performance. This means per-line `@effect-diagnostics` comment directives cannot re-enable it.

    To allow directives to override disabled rules, set `skipDisabledOptimization` to `true`:

    ```jsonc theme={null}
    {
      "compilerOptions": {
        "plugins": [
          {
            "name": "@effect/language-service",
            "skipDisabledOptimization": true
          }
        ]
      }
    }
    ```

    With this enabled, you can selectively activate a disabled rule for a specific line:

    ```typescript theme={null}
    // @effect-diagnostics-next-line strictEffectProvide:warning
    Effect.provide(program, layer)
    ```

    <Warning>
      Enabling `skipDisabledOptimization` may increase memory usage and slow down diagnostics because every disabled rule is still processed on every file.
    </Warning>
  </Accordion>

  <Accordion title="Hover responses are slow">
    Two settings can affect hover performance:

    **`layerGraphFollowDepth`**

    The `layerGraphFollowDepth` option controls how many levels of symbol references the layer graph extractor follows when building hover diagrams. The default is `0` (only direct references). Increasing this value makes hover responses more detailed but significantly slower for large layer graphs.

    ```jsonc theme={null}
    {
      "compilerOptions": {
        "plugins": [
          {
            "name": "@effect/language-service",
            // Increase only if you need deeper layer graphs; keep at 0 for best performance
            "layerGraphFollowDepth": 0
          }
        ]
      }
    }
    ```

    **Go-based compiler performance**

    `effect-tsgo` uses the Go-based TypeScript compiler, which is significantly faster than the classic TypeScript compiler for large projects. If you are experiencing general slowness beyond hover, ensure you are not accidentally running the classic TypeScript server in parallel (see the duplicate diagnostics entry above).
  </Accordion>
</AccordionGroup>