windmill-labs/windmill · warning

Kept existing f/${f}/${name} (hand-written — not the generat

Error message

Kept existing f/${f}/${name} (hand-written — not the generated pointer)

What it means

During `wmill pipeline docs` generation (generatePipelineDocs), each generated doc file is written as a pointer into Windmill. If an existing file on disk contains anything other than that exact generated pointer, it is treated as hand-written documentation and left untouched, with this warning. Generation never overwrites human edits.

Source

Thrown at cli/src/commands/pipeline/docs.ts:287

  // file that merely references `@PIPELINE.md` alongside its own content.
  const written = ["PIPELINE.md"];
  const pointers: Array<[string, string]> = [
    ["AGENTS.md", `See @PIPELINE.md for this pipeline's graph, assets, and how to run it.\n`],
    ["CLAUDE.md", `Instructions are in @PIPELINE.md\n`],
  ];
  for (const [name, content] of pointers) {
    const p = path.join(folderDir, name);
    if (existsSync(p)) {
      let existing: string;
      try {
        existing = readFileSync(p, "utf-8");
      } catch {
        continue;
      }
      // Anything other than our exact generated pointer is treated as
      // hand-written and preserved (writing when identical is a no-op anyway).
      if (existing.trim() !== content.trim()) {
        log.warn(
          colors.yellow(`Kept existing f/${f}/${name} (hand-written — not the generated pointer)`),
        );
        continue;
      }
    }
    await writeFile(p, content, "utf-8");
    written.push(name);
  }
  log.info(colors.green(`✓ Wrote ${written.join(", ")} to f/${f}`));
}

View on GitHub (pinned to e474e8803c)

Solutions

1. If the hand-written content is what you want, do nothing — the file is intentionally preserved.
2. If you want the generated pointer back, delete the local file (or restore the pointer text) and rerun the docs generation.
3. Diff the file against a freshly generated pointer to decide which version to keep.
4. Keep hand-written docs out of the generation output path so generation and authorship don't fight.

Example fix

# before: generation warns and keeps your edits
wmill pipeline docs  # -> Kept existing f/myflow/docs (hand-written ...)
# after: regenerate from scratch
rm f/myflow/docs.md && wmill pipeline docs

// detect hand-edited docs before generating
import { readFileSync, existsSync } from 'fs';
const p = 'f/myflow/docs.md';
if (existsSync(p)) {
  const existing = readFileSync(p, 'utf-8').trim();
  if (!existing.startsWith('<docs-pointer')) {
    console.warn(`${p} is hand-written; generation will keep it`);
  }
}

When it happens

Trigger: Running docs generation when f/<flow>/<name> docs already exist locally and their content differs from the generated pointer (someone edited the file, or it predates the pointer scheme).

Common situations: A teammate wrote custom Markdown docs for a flow; docs were generated by an older CLI version with a different pointer format; the file was partially hand-edited after generation.

Related errors

• File already exists: + scriptCodeFileFullPath
• File already exists: + scriptMetadataFileFullPath
• File already exists: ${filePath}
• Could not fetch datatable schemas: ${err.message}
• App ${appPath} not found

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/ebfc0a0f00521e30. Report an issue: GitHub.