microsoft/TypeScript · error · Error

Non-comment test content appears before the first '// @Filen

Error message

Non-comment test content appears before the first '// @Filename' directive

What it means

Thrown by the multi-file test parser in harnessIO.ts:1302. When the parser hits the first `// @Filename` directive in a test file, it checks that any content already accumulated (`currentFileContent`) consists only of comments (skipTrivia reaches end of string). If real code precedes the first directive, the throw fires — that code has no file to belong to.

Source

Thrown at src/harness/harnessIO.ts:1302

                        content: currentFileContent!, // TODO: GH#18217
                        name: currentFileName,
                        fileOptions: currentFileOptions,
                        originalFilePath: fileName,
                        references: refs,
                    };
                    testUnitData.push(newTestFile);

                    // Reset local data
                    currentFileContent = undefined;
                    currentFileOptions = {};
                    currentFileName = testMetaData[2].trim();
                    refs = [];
                }
                else {
                    // First metadata marker in the file
                    currentFileName = testMetaData[2].trim();
                    if (currentFileContent && ts.skipTrivia(currentFileContent, 0, /*stopAfterLineBreak*/ false, /*stopAtComments*/ false) !== currentFileContent.length) {
                        throw new Error("Non-comment test content appears before the first '// @Filename' directive");
                    }
                    currentFileContent = "";
                }
            }
            else {
                // Subfile content line
                // Append to the current subfile content, inserting a newline needed
                if (currentFileContent === undefined) {
                    currentFileContent = "";
                }
                else if (currentFileContent !== "") {
                    // End-of-line
                    currentFileContent = currentFileContent + "\n";
                }
                currentFileContent = currentFileContent + line;
            }
        }

View on GitHub (pinned to b465fdbfe1)

Solutions

Move every line of real code under a `// @Filename: <name>.ts` directive so nothing but comments precedes the first directive.
Convert stray preamble into a comment block (line-leading `//`).
Add an explicit `// @Filename: preamble.ts` directive to host the early code.

Example fix

// before — code before first directive
import { x } from "y";
// @Filename: a.ts
export const z = x;

// after — preamble lives under a directive (or as a comment)
// @Filename: imp.ts
import { x } from "y";
// @Filename: a.ts
export const z = x;

Defensive patterns

Strategy: validation

Validate before calling

// Lint a multifile test source before the parser throws.
function assertNoCodeBeforeFirstFilenameDirective(source: string): void {
  const idx = source.indexOf('// @Filename');
  if (idx < 0) return; // not a multifile test
  const head = source.slice(0, idx);
  const nonComment = head.split(/\r?\n/).filter(l => l.trim() !== '' && !l.trim().startsWith('//'));
  if (nonComment.length > 0) {
    throw new Error(`Move these lines under a // @Filename directive: ${nonComment.join(' | ')}`);
  }
}

Type guard

function beginsWithFilenameDirectiveOrComments(source: string): boolean {
  const head = source.slice(0, source.indexOf('// @Filename'));
  return head.split(/\r?\n/).every(l => l.trim() === '' || l.trim().startsWith('//'));
}

Prevention

Start every multifile test with the option/annotation comment block immediately followed by the first // @Filename directive.
Run a quick linter that rejects non-comment lines before the first // @Filename.
When concatenating single-file tests, prepend a // @Filename directive before each block.

When it happens

Trigger: A compiler test file begins with executable TypeScript/JavaScript statements or a file-level declaration before the first `// @Filename` directive. Only comment lines (the metadata/option block) are permitted before the first directive.

Common situations: Author pastes source code at the top of a test file above the `// @Filename` block; an editor auto-inserts an import or shebang line at the head; concatenating single-file tests into a multi-file test without moving the preamble under a `// @Filename`.

Related errors

AI-assisted analysis of microsoft/TypeScript@b465fdbfe1 (2026-08-12). Data as JSON: /api/errors/341e8f6bad392c1f. Report an issue: GitHub.