Skip to content

Change #528 breaks existing canRetry logic and interface contracts #549

Description

@jeffreyzant

Description

Invoking the canRetry method with a null $error argument value which is introduced in #528 is a major issue and can break existing implementations of canRetry. The definition of RetryableJobInterface clearly states:

* @param int $attempt The attempt number 
* @param \Exception|\Throwable $error The error from the last execution of the job

In our jobs, we rely on the error instance to determine whether a job should be retried. Calling canRetry with a null error value and ignoring the job's failure has already led to significant data loss.

Example of an existing implementation that depends on the error:

/**
 * Defines if the job can be retryed automatically.
 */
public function canRetry($attempt, $error): bool
{
    if ($error instanceof SpecificException) {
        if ($attempt < 12) {
            return true;
        }
    }

    return false;
}

The change alters the contract of the interface in a backward-incompatible way and undermines the intended retry logic.

Package version

2.3.8

PHP version

8.4.15

Activity

  1. terabytesoftw commented on Feb 17, 2026

    @terabytesoftw
    Member

    public function canRetry(int $attempt, ?Throwable $error): bool;

  2. rob006 commented on Feb 17, 2026

    @rob006

    @terabytesoftw this was changed in PR targeting 3.0 (BTW: method signature was changed, but no mention of this in changelog) https://github.com/yiisoft/yii2-queue/pull/545/changes#diff-4956183588dc990c08e9a8a5eb03db4b496bec0d85062a35f2e1e7e79c84c9e8

    Signature from last release:

    /**
    * @param int $attempt number
    * @param \Exception|\Throwable $error from last execute of the job
    * @return bool
    */
    public function canRetry($attempt, $error);

  3. terabytesoftw commented on Feb 17, 2026

    @terabytesoftw
    Member

    @terabytesoftw this was changed in PR targeting 3.0 (BTW: method signature was changed, but no mention of this in changelog) https://github.com/yiisoft/yii2-queue/pull/545/changes#diff-4956183588dc990c08e9a8a5eb03db4b496bec0d85062a35f2e1e7e79c84c9e8

    Signature from last release:

    yii2-queue/src/RetryableJobInterface.php

    Lines 22 to 27 in e0f935e

     /** 
      * @param int $attempt number 
      * @param \Exception|\Throwable $error from last execute of the job 
      * @return bool 
      */ 
     public function canRetry($attempt, $error);
    

    Good catch, we'll add it to CHANGELOG.md and UPGRADE.md before the release.

  4. terabytesoftw commented on Feb 20, 2026

    @terabytesoftw
    Member

    @jeffreyzant Here's the fix, could you test the branch if everything works as it should? Thanks.

  5. terabytesoftw commented on Feb 21, 2026

    @terabytesoftw
    Member

    @rob006 You could take a look at the PR, thanks.

  6. NicoNuernberger commented on Sep 16, 2026

    @NicoNuernberger

    Quick question - When can one expect this fix to make its way into the master branch?

  7. jeffreyzant commented on Sep 16, 2026

    @jeffreyzant
    Author

    @NicoNuernberger I'm not a maintainer, but I don't think this will make it into the master branch, as they chose to implement it for v3. Since it's a breaking change, the revert is only being merged into the v2 tags.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions