zzz updating plugin: why plugin updates get stuck

zzz updating plugin is a status, not an error. Brief appearance is normal; never ending means the update is stuck in download, extraction, dependencies, or restart.

What zzz means

It is placeholder text shown while the update flow runs. An update has four stages: version resolution, download, extraction and dependencies, restart and load (source).

All four display the same text. The UI does not separate stages; system logs do.

Do not search it as an error code. Results are about general update failures, not stuck stages; identify the stage first.

Four causes

Four causes cover most stuck updates.

1. Slow or interrupted download. Network, mirror, or proxy; logs stop at download and progress does not move.
2. Extraction or disk issue. Insufficient space, permissions, or long paths; logs report extraction or write failures.
3. Dependency resolution conflict. New dependencies conflict with installed ones, or a lock file is stale; logs stop at resolution.
4. Restart load failure. The update wrote files but startup fails to load; the UI may still show updating while the plugin is unusable.

Fixes differ completely. Download needs network or mirror, extraction needs disk and permissions, dependencies need a lock cleanup or rollback, loading needs plugin logs.

Identify the stage

Without logs, any judgment is a guess.

1. Watch progress. No change for a long time suggests download; jumping back suggests resolution.
2. Read system logs. The last record shows the stage.
3. Check disk and permissions. No space or a read-only directory fails at extraction.
4. Check the installed version. Changed but unusable suggests loading; unchanged suggests not finished.

"Version changed but plugin broken" is often misread as not updated. The update completed and loading failed; fix loading rather than downloading again.

"Version unchanged" means it did not finish. Read the last stage and handle that cause.

Recovery order: light to heavy

Sort by cost and preserve the scene.

1. Wait a minute. Large packages on slow networks take time; do not interrupt immediately.
2. Read logs to identify the stage.
3. Change network or mirror. Only helps download; retry and watch progress.
4. Clear locks and cache. For resolution stalls; record the current version before clearing.
5. Reinstall the plugin. If the first four fail, uninstall and reinstall after backing up configuration.
6. Roll back the version. If the new version itself is broken, return to the previous one and pin it.

Do not reinstall first. It destroys the scene and hides whether the issue was download, dependencies, or loading.

Interrupt carefully. Download interruptions are usually safe; extraction and dependency interruptions can leave partial output that requires a fresh update.

When it is already done

Three cases look stuck but are complete.

1. Version changed and function works. Only the UI status is stale; refresh or restart.
2. Plugin works but the list shows an old version. Cache not updated; verify with dsh plugin --profile web list.
3. Write completed, waiting for restart. Some plugins need a restart; the UI waits for the action.

Judge by version and function, not the text. If both are correct, stop waiting.

Use the CLI to confirm. dsh plugin --profile web list shows the installed version more reliably than the UI.

Two typical scenes

The stage matters more than the text.

1. Mirror changed, still stuck. Mirrors affect download only. If logs stop at dependency resolution, changing ten mirrors will not move; clear locks or roll back.
2. Update finished but the plugin errors. The status still says updating, but the version changed and loading fails. This is the fourth cause; read load logs and compatibility, not download.

Both share "text unchanged, stage changed." The UI alone leads to wrong conclusions; the last log record is the evidence.

Prevention: three things before updating

Stuck updates are preventable with two minutes of preparation.

1. Check disk space: leave several times the plugin size free.
2. Check network and mirror: switch mirrors before timeouts.
3. Record the current version: rollback depends on it; "latest" is not a record.

Update one plugin at a time. Batch updates hide which plugin caused the stall.

Run a minimal function after updating. Do not discover a broken plugin a day later; verify one entry or command immediately.

Next steps

Read the stage, then recover by cost. For the normal single-plugin flow, read Updating a single plugin. For hot reload failures, read Plugin HMR reload failure. For the Hub update dialog, read How to install from DSH Plugin Hub.

Sources: DSH Plugin Hub 2.2.5 screenshot index, dshplugin/dsh-plugin-hub, dsh CLI README