astral-sh/ruff · error

{flag} <reason> cannot contain newline characters

Error message

{flag} <reason> cannot contain newline characters

What it means

`ruff check --add-noqa [reason]` and `--add-ignore [reason]` embed the reason into generated suppression comments; a newline would corrupt the comment syntax, so any '\n' or '\r' in the reason is rejected before work starts.

Source

Thrown at crates/ruff/src/lib.rs:338

        warn_user!("Detected debug build without --no-cache.");
    }

    let suppression = cli
        .add_noqa
        .as_ref()
        .map(|reason| (reason, SuppressionKind::Noqa, "--add-noqa"))
        .or_else(|| {
            cli.add_ignore
                .as_ref()
                .map(|reason| (reason, SuppressionKind::Ignore, "--add-ignore"))
        });

    if let Some((reason, suppression_kind, flag)) = suppression {
        if !fix_mode.is_generate() {
            warn_user!("--fix is incompatible with {flag}.");
        }
        if reason.contains(['\n', '\r']) {
            return Err(anyhow::anyhow!(
                "{flag} <reason> cannot contain newline characters"
            ));
        }

        let reason_opt = (!reason.is_empty()).then_some(reason.as_str());

        let modifications = commands::add_noqa::add_noqa(
            &files,
            &pyproject_config,
            &config_arguments,
            reason_opt,
            suppression_kind,
        )?;
        if modifications > 0 && config_arguments.log_level >= LogLevel::Default {
            let s = if modifications == 1 { "" } else { "s" };
            let suppression = match suppression_kind {
                SuppressionKind::Noqa => "noqa directive",
                SuppressionKind::Ignore => "ignore comment",

View on GitHub (pinned to 672bb4edf0)

Solutions

1. Strip newlines first: `ruff check --add-noqa "$(printf '%s' "$reason" | tr -d '\r\n')"`
2. Keep the reason to one line and link the ticket instead
3. If you also pass --fix, remove it: it is incompatible with --add-noqa/--add-ignore (warned separately)

Example fix

# before
ruff check --add-noqa "$MULTILINE_REASON" src/

# after
ruff check --add-noqa "$(printf '%s' "$MULTILINE_REASON" | tr -d '\r\n')" src/

reason=$(printf '%s' "$reason" | tr -d '\r\n')
ruff check --add-noqa "$reason" "$target"

When it happens

Trigger: Passing a multi-line reason, e.g. `ruff check --add-noqa "$(printf 'see #123\nfollow-up')"`, or a reason variable containing line breaks from a heredoc/file read.

Common situations: CI scripts building reasons from PR descriptions or multi-line files; shell quoting with $'...' that inserts \n; copy-pasting reasons with trailing line breaks.

Related errors

• Provided project path `{project}` is not a directory
• {e}
• could not find task named `{}`
• could not find any tasks matching the given criteria
• found more than one task matching the given criteria

AI-assisted analysis of astral-sh/ruff@672bb4edf0 (2026-08-16). Data as JSON: /api/errors/cd93b4234f778b26. Report an issue: GitHub.