Diagnostic severity

Understand severity levels and learn how to override them globally with diagnosticSeverity or per-line with directive comments.

Every Effect diagnostic has a default severity that determines how it appears in your editor and whether it affects tsc’s exit code. You can override any diagnostic’s severity globally in tsconfig.json or locally using directive comments.

Severity levels

Level	Symbol	Meaning
error	❌	A hard error. Breaks the tsc exit code by default.
warning	⚠️	A warning. Visible in editors; does not break tsc by default.
suggestion	💡	A code suggestion. Shown as a hint in editors.
message	💬	An informational message. Lowest visible severity.
off	➖	Disabled. The diagnostic is not reported at all.

Diagnostics marked ➖ in the diagnostics table are off by default. You must explicitly set them in diagnosticSeverity to enable them.

Global severity overrides

Use the diagnosticSeverity plugin option in tsconfig.json to override the default severity for any rule.

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service",
        "diagnosticSeverity": {
          // Enable an off-by-default rule at warning severity
          "strictEffectProvide": "warning",
          // Downgrade an error to a warning
          "floatingEffect": "warning",
          // Silence a rule entirely
          "catchUnfailableEffect": "off"
        }
      }
    ]
  }
}

Common patterns

Enable an off-by-default rule

Rules default to off when they are opinionated or project-specific. Enable them by assigning any active severity:

"diagnosticSeverity": {
  "globalFetch": "warning",
  "nodeBuiltinImport": "suggestion"
}

Downgrade an error to a warning

Useful when adopting a new diagnostic incrementally:

"diagnosticSeverity": {
  "missingEffectError": "warning"
}

Disable a built-in rule

"diagnosticSeverity": {
  "effectGenUsesAdapter": "off"
}

Exit code control

By default, only error-severity diagnostics affect tsc’s exit code. Use these options to adjust that behaviour:

ignoreEffectSuggestionsInTscExitCode (default: true)

When true, Effect diagnostics at suggestion or message severity do not cause a non-zero tsc exit code. Diagnostics are still reported; they just won’t fail CI.

Set to false if you want suggestions to be treated as build failures:

"ignoreEffectSuggestionsInTscExitCode": false

ignoreEffectWarningsInTscExitCode (default: false)

When true, Effect diagnostics at warning severity do not cause a non-zero tsc exit code. Useful when you want warning-level feedback in your editor without blocking CI.

"ignoreEffectWarningsInTscExitCode": true

ignoreEffectErrorsInTscExitCode (default: false)

When true, Effect error-severity diagnostics do not cause a non-zero tsc exit code. This lets you run tsc in check mode without blocking on Effect-specific errors.

"ignoreEffectErrorsInTscExitCode": true

Directive comments

You can override diagnostic severity for a specific block or line using directive comments, without touching tsconfig.json.

Block-level: @effect-diagnostics

A @effect-diagnostics comment applies until it is overridden by another directive or the end of the file.

// @effect-diagnostics floatingEffect:off
const ignored = Effect.succeed(42) // not reported

// @effect-diagnostics floatingEffect:error
const alsoIgnored = Effect.succeed(42) // reported again

You can combine multiple rules in a single directive:

// @effect-diagnostics floatingEffect:off missingEffectError:warning

Line-level: @effect-diagnostics-next-line

A @effect-diagnostics-next-line comment applies only to the immediately following line.

// @effect-diagnostics-next-line floatingEffect:off
const temporary = Effect.succeed(42) // not reported for this line only
const reported = Effect.succeed(42) // back to default

Your editor will offer completion suggestions for both directive forms, including available rule names and severity values.

Directive-based enabling with skipDisabledOptimization

By default, globally disabled diagnostics are skipped entirely during analysis for performance. This means @effect-diagnostics directives cannot re-enable a rule that has "off" in diagnosticSeverity.

Set skipDisabledOptimization: true to process all diagnostics regardless of their global setting, allowing directive comments to re-enable individual rules on a per-section basis:

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@effect/language-service",
        "diagnosticSeverity": {
          "globalFetch": "off"
        },
        "skipDisabledOptimization": true
      }
    ]
  }
}

// @effect-diagnostics globalFetch:warning
fetch("/api/data") // reported as warning

// @effect-diagnostics globalFetch:off
fetch("/api/other") // silenced again

Enabling skipDisabledOptimization increases analysis time proportional to the number of disabled rules. Only enable it when you actively use directive-based overrides for globally disabled diagnostics.