What causes "deprecated use session.addGutterDecoration" in ajaxorg/ace?

deprecated use session.addGutterDecoration

Error message

deprecated use session.addGutterDecoration

What it means

A deprecation warning emitted by GutterLayer.addGutterDecoration (also surfaced through Renderer.addGutterDecoration). Decoration bookkeeping moved to the session, so the layer method now just warns and forwards to session.addGutterDecoration.

Source

Thrown at src/layer/gutter.js:60

    /**
     * @param {EditSession} session
     */
    setSession(session) {
        if (this.session)
            this.session.off("change", this.$updateAnnotations);
        this.session = session;
        if (session)
            session.on("change", this.$updateAnnotations);
    }

    /**
     * @param {number} row
     * @param {string} className
     */
    addGutterDecoration(row, className) {
        if (window.console)
            console.warn && console.warn("deprecated use session.addGutterDecoration");
        this.session.addGutterDecoration(row, className);
    }

    /**
     * @param {number} row
     * @param {string} className
     */
    removeGutterDecoration(row, className) {
        if (window.console)
            console.warn && console.warn("deprecated use session.removeGutterDecoration");
        this.session.removeGutterDecoration(row, className);
    }

    /**
     * @param {any[]} annotations
     */
    setAnnotations(annotations) {
        // iterate over sparse array

View on GitHub (pinned to 2c1eddc392)

Solutions

Call editor.session.addGutterDecoration(row, className) instead
Remove renderer.addGutterDecoration wrapper calls and route all gutter decoration through the session
Remember to clean up with session.removeGutterDecoration(row, className)
Warning is benign — the call still takes effect via delegation

Example fix

// before
editor.renderer.addGutterDecoration(4, 'error_gutter');
// after
editor.session.addGutterDecoration(4, 'error_gutter');

Defensive patterns

Strategy: validation

Validate before calling

if (typeof editor.session.addGutterDecoration !== 'function') throw new Error('session gutter API unavailable; upgrade ace');
editor.session.addGutterDecoration(row, className);

Try / catch

try {
  editor.session.addGutterDecoration(row, className);
} catch (e) {
  console.error('gutter decoration failed', e);
}

Prevention

Always decorate gutters via session.addGutterDecoration/removeGutterDecoration, never the renderer
Grep for 'renderer.addGutterDecoration' and migrate call sites
Pair every decoration with a remove call to avoid leaks
Watch CI console output for deprecation warnings to catch regressions

When it happens

Trigger: Calling editor.renderer.addGutterDecoration(row, className) — the renderer-level API — in code written against older Ace versions.

Common situations: Plugins that highlight lines in the gutter (breakpoints, lint markers) written for old Ace; copied StackOverflow snippets using renderer.addGutterDecoration.

Related errors

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