Unexpected "'Type' is declared but its value is never read." error with jsdoc @import syntax

🔎 Search Terms

jsdoc @import "is declared but its value is never read"

🕗 Version & Regression Information

I have seen this error since the introduction of @import in jsdoc comments (TS 5.5 if i recall correctly)

⏯ Playground Link

No response

💻 Code

I made a testcase repo https://github.com/DavidBruant/jsdoc-import-unused-testcase
It is as reduced as a managed to make it

The code :

/** @import {ImportedType} from './types.d.ts' */

function id() { return undefined }

/** @type {Set<ImportedType>} */
export const phases = new Set(['a', 'b'])

The types.d.ts file:

export type ImportedType = 'a' | 'b'

🙁 Actual behavior

tsc and VSCodium both say:

code.js:1:5 - error TS6133: 'ImportedType' is declared but its value is never read.

1 /** @import {ImportedType} from './types.d.ts' */

🙂 Expected behavior

There shouldn't be an error because of the line using the type : /** @type {Set<ImportedType>} */

We've had this error in plently of places. It also seems like it occurs more regulary when the type is used within a generics

Additional information about the issue

For some reason, removing function id() { return undefined } from the code solves the problem while it seems completely unrelated to the problem

Interestingly, I can't repro it using the bug workbench: workbench

I think I have the same problem.

TypeScript reports that an import is useless when used in the return type of a function. bad.js 👎
But it doesn't report a problem if it's used in the return type of two functions. good1.js 👍
Or if used in the type of a variable good2.js 👍

package.json

{
  "name": "testcase",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@types/node": "22.10.5",
    "playwright": "1.49.1",
    "typescript": "5.7.3"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "module": "nodenext",
    "noUnusedLocals": true,
    "noEmit": true,
    "checkJs": true
  }
}

bad.js

/**
 * @import { Page } from "playwright"
 */

/**
 * @returns {Page|undefined}
 */
function foo() {
    return undefined;
}

console.log(foo());

good1.js

/**
 * @import { Page } from "playwright"
 */

/**
 * @returns {Page|undefined}
 */
function foo() {
    return undefined;
}

/**
 * @returns {Page|undefined}
 */
function bar() {
    return undefined;
}

console.log(foo(), bar());

good2.js

/**
 * @import { Page } from "playwright"
 */

/**
 * @type {Page|undefined}
 */
let foo;

console.log(foo);

npm install

npx tsc

bad.js:2:4 - error TS6133: 'Page' is declared but its value is never read.

2  * @import { Page } from "playwright"
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Found 1 error in bad.js:2

While we wait for the fix to be merged, here is a (surprising) workaround:

/**
 * @import { Page } from "playwright"
 */
'ignore';

// ...

I see that TypeScript 5.8.3 has recently been released

When i compare 5.8.2 and 5.8.3, i can see the commit ee3dd72 which was the result of merging #60921 if i understand correctly

so i expected the bug described in this issue to be fixed

However, i did the reproduction steps in the testcase repo (i updated TS to 5.8.3)
https://github.com/DavidBruant/jsdoc-import-unused-testcase
and i can still see the same bug both in VSCodium (i checked the TS version being used in the bottom right corner) and tsc

I'm not sure where the problem is

Maybe i misunderstood the pull request
or the content of the 5.8.3 release
or the typescript release process
or maybe what's available on npm is slightly different
or something else?

If anyone sees this message, can you check whether the issue is fixed on your end, please? Thank you 🙏

If anyone sees this message, can you check whether the issue is fixed on your end, please? Thank you 🙏

I've tested my example #60908 (comment). I still get the error with TypeScript 5.8.3.

Jake Bailey (@jakebailey)

I'd love to reopen this issue but don't have the permissions to

Jake Bailey (@jakebailey) could you to reopen this issue, please?

I created a testcase in Bug Workbench: https://www.typescriptlang.org/dev/bug-workbench/?noUnusedLocals=true&checkJs=true&moduleResolution=99&module=199&ts=5.8.3#code/PTAEAEFsHsBMFcA2BTAXKAdnZHkA8AXAKBAhgRQCVkBnaReAgS2g3S1h32NPCwFUM8GslgAZaAGMAhohroCAJ3jISYcJIAWySQGsAUvNBKVRNRABmTFBmmQ0xgJ4AHWgDpYbgjSL5n0RQInV1ALaGhQAF5QGiUmDABzM3NwKxs7BzTkNwArH2AAKgKiUAKIJkh-QNAAb1Dw0ABfUMVoSFAAIjdgAhd3T28OkoLgM0Li0ohFZAJ4RQwaWrDoRuHRi3gMSWZWUAAjaUUACgBKWpLQS+nZ+c6DgC8OgG4iVaJJVjoUN0RoBKODscTicnkA

// @module: nodenext
// @moduleResolution: nodenext
// @noUnusedLocals: true
// @checkJs: true

// @filename: types.d.ts
export type foo = string


// @filename: file.js
/**
 * @import { foo } from "./types.d.ts"
 */

/**
 * @returns {foo}
 */
function bar() {
    return "baz";
}

console.log(bar());

'foo' is declared but its value is never read.

There is no error when:

@module: nodenext and @moduleResolution: nodenext are removed: https://www.typescriptlang.org/dev/bug-workbench/?noUnusedLocals=true&checkJs=true&ts=5.8.3#code/PTAEA...o8tAA
foo is used two times: https://www.typescriptlang.org/dev/bug-workbench/?noUnusedLocals=true&checkJs=true&moduleResolution=99&module=199&ts=5.8.3#code/PTAEA...Ep5AA
foo is used in @type: https://www.typescriptlang.org/dev/bug-workbench/?noUnusedLocals=true&checkJs=true&moduleResolution=99&module=199&ts=5.8.3#code/PTAEA...EoDoA
; is added after import: https://www.typescriptlang.org/dev/bug-workbench/?noUnusedLocals=true&checkJs=true&moduleResolution=99&module=199&ts=5.8.3#code/PTAEA...zmMgA

This is fixed. With module and moduleResolution set to nodenext, allowJs, checkJs, and noUnusedLocals, a single JSDoc @returns {Foo} use no longer reports TS6133 for /** @import { Foo } from "./types.d.ts" */.

The last affected nightly was 5.9.0-dev.20250317; 5.9.0-dev.20250318, TypeScript 6.0.3, and current native TypeScript are clean. The change was made by PR #60921.

Navigation Menu

Repository navigation

Unexpected "'Type' is declared but its value is never read." error with jsdoc @import syntax #60908

🔎 Search Terms

🕗 Version & Regression Information

⏯ Playground Link

💻 Code

🙁 Actual behavior

🙂 Expected behavior

Additional information about the issue

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Unexpected "'Type' is declared but its value is never read." error with jsdoc @import syntax #60908

Description

🔎 Search Terms

🕗 Version & Regression Information

⏯ Playground Link

💻 Code

🙁 Actual behavior

🙂 Expected behavior

Additional information about the issue

Activity

Andarist commented on Jan 3, 2025

regseb commented on Jan 11, 2025

mantoni commented on Mar 12, 2025

DavidBruant commented on Apr 22, 2025

regseb commented on Apr 24, 2025

DavidBruant commented on Apr 24, 2025

regseb commented on Apr 24, 2025

RyanCavanaugh commented on Sep 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions