vitest-dev/vitest · error · Error

Test file " " was not registered, so it cannot be updated…

Error message

Test file "${id}" was not registered, so it cannot be updated using the API.

What it means

The Vitest WebSocket API exposes saveTestFile(id, content) for tools (like the VS Code extension or UI) to write test file contents. It checks that the id is both registered in ctx.state.filesMap and exists on disk. If either fails, the file was never collected/registered by Vitest, so the API refuses to write it.

Solutions

Ensure the file id matches a path that Vitest has actually collected (check getFiles/getPaths from the same API).
Wait for Vitest's collection to finish before issuing saveTestFile.
If the file was renamed/moved, update the client to use the new registered path.

Defensive patterns

Strategy: validation

Validate before calling

// before calling saveTestFile via RPC:
const files = await rpc.getFiles()
if (!files.some(f => f.id === targetId)) {
  // file not registered; skip the save
}

Try / catch

try {
  await api.saveTestFile(id, content)
} catch (e) {
  if (e.message.includes('was not registered')) {
    // refresh file list and retry, or notify user
  } else throw e
}

Prevention

Always verify a file id is in getFiles() before calling saveTestFile.
Refresh the file list after rename/delete operations before saving.

When it happens

Trigger: A client calls saveTestFile with a file path that Vitest has not collected (not in the current test glob) or that doesn't exist on disk; calling the RPC method before Vitest has finished its initial collection.

Common situations: Editor extension trying to save a file outside the configured test.include; race condition where save is attempted before collection completes; stale id after a file was renamed/deleted.

Related errors

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/099fd92676e66cd9. Report an issue: GitHub.

Appendix: source

Thrown at packages/vitest/src/api/setup.ts:76

  function setupClient(ws: WebSocket) {
    const rpc = createBirpc<WebSocketEvents, WebSocketHandlers>(
      {
        getFiles() {
          return ctx.state.getFiles()
        },
        getPaths() {
          return ctx.state.getPaths()
        },
        async readTestFile(id) {
          if (!ctx.state.filesMap.has(id) || !existsSync(id)) {
            return null
          }
          return fs.readFile(id, 'utf-8')
        },
        async saveTestFile(id, content) {
          if (!ctx.state.filesMap.has(id) || !existsSync(id)) {
            throw new Error(
              `Test file "${id}" was not registered, so it cannot be updated using the API.`,
            )
          }
          // silently ignore write attempts if not allowed
          if (!ctx.config.api.allowWrite) {
            return
          }
          return fs.writeFile(id, content, 'utf-8')
        },
        async rerun(files, resetTestNamePattern) {
          // silently ignore exec attempts if not allowed
          if (!ctx.config.api.allowExec) {
            return
          }
          await ctx.rerunFiles(files, undefined, true, resetTestNamePattern)
        },
        async rerunTask(id) {
          // silently ignore exec attempts if not allowed

View on GitHub (pinned to 1fa9837ec2)