rectorphp/rector · error · ShouldNotHappenException

"%s" is deprecated, as data provider docblock typing is not

Error message

"%s" is deprecated, as data provider docblock typing is not relevant to code quality

What it means

Rector\TypeDeclarationDocblocks\Rector\Class_\AddReturnDocblockDataProviderRector is deprecated: refactor() throws Rector\Exception\ShouldNotHappenException on the first Class_ node. It added @return docblocks to PHPUnit data-provider methods, which - like its sibling rules - is typing that never affects code quality and only adds churn to test files.

Source

Thrown at rules/TypeDeclarationDocblocks/Rector/Class_/AddReturnDocblockDataProviderRector.php:76

     * @return array<array<string>>
     */
    public function provideItems()
    {
        return [
            [['item1', 'item2']],
            [['item3', 'item4']],
        ];
    }
}
CODE_SAMPLE
)]);
    }
    /**
     * @param Class_ $node
     */
    public function refactor(Node $node): ?Node
    {
        throw new ShouldNotHappenException(sprintf('"%s" is deprecated, as data provider docblock typing is not relevant to code quality', self::class));
    }
}

View on GitHub (pinned to 408fcb0ff1)

Solutions

Remove AddReturnDocblockDataProviderRector from rector.php.
Add provider @return docblocks by hand only where a reader benefits.
Track provider conventions in review checklists instead of automated rewrites.

Example fix

// before (rector.php)
->withRules([AddReturnDocblockDataProviderRector::class])

// after (rector.php) - rule removed; no replacement needed

Defensive patterns

Strategy: validation

Validate before calling

use Rector\TypeDeclarationDocblocks\Rector\Class_\AddReturnDocblockDataProviderRector;

$rules = [/* your list */ AddReturnDocblockDataProviderRector::class];
if (in_array(AddReturnDocblockDataProviderRector::class, $rules, true)) {
    throw new InvalidArgumentException('Rule deprecated; data-provider typing is not a code-quality concern');
}

Try / catch

try {
    exit($rectorApplication->run());
} catch (\Rector\Exception\ShouldNotHappenException $e) {
    if (str_contains($e->getMessage(), 'AddReturnDocblockDataProviderRector')) {
        fwrite(STDERR, 'Remove the rule; type providers by hand only where a reader benefits.' . PHP_EOL);
        exit(1);
    }
    throw $e;
}

Prevention

Maintain a project allowlist of rector rules and validate it against rector's current rule set on upgrade.
Skip docblock-generation rules for PHPUnit code entirely - the provider family was deprecated as noise.
Fail CI early on deprecated class names in rector.php so one stale entry cannot break every run.

When it happens

Trigger: The rule is still referenced in rector.php and rector visits any class declaration; refactor() throws on the first Class_ node of the run.

Common situations: Copied 'full typing' rule bundles; CI failing immediately after upgrading rector past the removal; separate rector configs for test directories that still list the rule.

Related errors

AI-assisted analysis of rectorphp/rector@408fcb0ff1 (2026-08-21). Data as JSON: /api/errors/847bed00902077aa. Report an issue: GitHub.