Use of document.insertNewLine is deprecated. Use insertMerge

Error message

Use of document.insertNewLine is deprecated. Use insertMergedLines(position, ['', '']) instead.

What it means

A deprecation warning printed by Document.insertNewLine. Inserting a newline is now expressed uniformly as insertMergedLines with an empty string before and after the break; the old method delegates to exactly that.

Source

Thrown at src/document.js:224

     * @param firstRow
     * @param lastRow
     * @returns {String[]}
     
     * @deprecated
     */
    removeLines(firstRow, lastRow) {
        console.warn("Use of document.removeLines is deprecated. Use the removeFullLines method instead.");
        return this.removeFullLines(firstRow, lastRow);
    }

    /**
     * @param position
     * @returns {Point}
     
     * @deprecated
     */
    insertNewLine(position) {
        console.warn("Use of document.insertNewLine is deprecated. Use insertMergedLines(position, ['', '']) instead.");
        return this.insertMergedLines(position, ["", ""]);
    }

    /**
     * Inserts a block of `text` at the indicated `position`.
     * @param {Point} position The position to start inserting at; it's an object that looks like `{ row: row, column: column}`
     * @param {String} text A chunk of text to insert
     * @returns {Point} The position ({row, column}) of the last line of `text`. If the length of `text` is 0, this function simply returns `position`. 
     
     **/
    insert(position, text) {
        // Only detect new lines if the document has no line break yet.
        if (this.getLength() <= 1)
            this.$detectNewLine(text);
        
        return this.insertMergedLines(position, this.$split(text));
    }

View on GitHub (pinned to 2c1eddc392)

Solutions

Replace doc.insertNewLine(pos) with doc.insertMergedLines(pos, ['', ''])
Consider doc.insert(pos, '\n') if you prefer plain text insertion
Grep for 'insertNewLine(' and migrate all call sites
The warning is harmless; behavior is a direct delegation

Example fix

// before
doc.insertNewLine({row: 2, column: 0});
// after
doc.insertMergedLines({row: 2, column: 0}, ['', '']);

Defensive patterns

Strategy: validation

Validate before calling

if (typeof doc.insertMergedLines !== 'function') throw new Error('insertMergedLines unavailable; upgrade ace');
doc.insertMergedLines(pos, ['', '']);

Type guard

function hasMergedLines(doc) { return doc && typeof doc.insertMergedLines === 'function'; }

Try / catch

try {
  doc.insertMergedLines(pos, ['', '']);
} catch (e) {
  console.error('newline insert failed', e);
}

Prevention

Replace insertNewLine with insertMergedLines(pos, ['', '']) or doc.insert(pos, '\n')
Suppress legacy method usage via lint rules forbidding the old names
Test against a pinned ace version where you've verified the modern API

When it happens

Trigger: Calling session.doc.insertNewLine(position) in legacy code that adds line breaks directly on the document.

Common situations: Old macros/plugins that build documents line by line; code copied from pre-rename Ace examples.

Related errors

AI-assisted analysis of ajaxorg/ace@2c1eddc392 (2026-08-30). Data as JSON: /api/errors/80c477ab5a25a054. Report an issue: GitHub.