lingochamp/FileDownloader · error · IllegalStateException

This task is dirty to restart, If you want to reuse this…

Error message

This task is dirty to restart, If you want to reuse this task, please invoke #reuse method manually and retry to restart again.

What it means

startTaskUnchecked() throws this IllegalStateException when the task is used (isUsing()) but not running and its hunter state indicates it is dirty — i.e. it has completed a lifecycle and cannot simply be restarted without reset. The library requires an explicit reuse() call to reset internal state before starting again.

Solutions

Call task.reuse() before invoking start() again.
Create a new task via FileDownloader.getImpl().create(url, path) instead of restarting the old one.

Example fix

// before
task.start(); // second time

// after
task.reuse();
task.start();

Defensive patterns

Strategy: validation

Validate before calling

if (task.isRunning()) return;
task.reuse();
task.start();

Try / catch

try { task.start(); } catch (IllegalStateException e) { task.reuse(); task.start(); }

Prevention

Call reuse() before any second start on the same instance.
Prefer new task creation over restarting old instances.
Centralize start logic in one helper that handles reuse.

When it happens

Trigger: Calling start() on a task object that was already started once and finished (paused, completed, or warned), without invoking BaseDownloadTask#reuse() first.

Common situations: Retrying a finished download with the same task instance; re-running a task after pause() without reuse().

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

AI-assisted analysis of lingochamp/FileDownloader@6237a8cac1 (2026-09-08). Data as JSON: /api/errors/b83098dbccc3626a. Report an issue: GitHub.

Appendix: source

Thrown at library/src/main/java/com/liulishuo/filedownloader/DownloadTask.java:319

                    + "BaseDownloadTask#start() manually to start this task or this task is started"
                    + " by the queue, there is an exception buried in there, because this task"
                    + " object is started two times without declare BaseDownloadTask#reuse() :"
                    + " 1. you invoke BaseDownloadTask#start() manually; "
                    + " 2. the queue start this task automatically.");
        }

        return startTaskUnchecked();
    }

    private int startTaskUnchecked() {
        if (isUsing()) {
            if (isRunning()) {
                throw new IllegalStateException(
                        FileDownloadUtils.formatString("This task is running %d, if you"
                                + " want to start the same task, please create a new one by"
                                + " FileDownloader.create", getId()));
            } else {
                throw new IllegalStateException("This task is dirty to restart, If you want to "
                        + "reuse this task, please invoke #reuse method manually and retry to "
                        + "restart again." + mHunter.toString());
            }
        }

        if (!isAttached()) {
            setAttachKeyDefault();
        }

        mHunter.intoLaunchPool();

        return getId();
    }

    // -------------- Another Operations ---------------------

    private final Object mPauseLock;

View on GitHub (pinned to 6237a8cac1)