Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Backstage Scaffolder task recovery automatically reopens a task that was interrupted while processing, then continues at its last unfinished step instead of starting the template over. It is disabled by default; set scaffolder.taskRecovery.enabled: true to opt in. In Backstage 1.55.0 (released September 15, 2026), the stable feature covers worker crashes, restarts, and timeouts: completed steps are skipped, their outputs are restored, and task secrets remain available until the task is completed or failed.
Recovery is not a rollback system and it does not make unsafe actions safe to repeat. If a template creates repositories, cloud resources, permissions, or other external objects, make each action idempotent or protect its side effect with ctx.checkpoint. If files in the task workspace must survive a restart, configure a workspace provider as well; enabling recovery alone does not serialize the filesystem.
As an Amazon Associate I earn from qualifying purchases.
How does Backstage scaffolder task recovery work?
When recovery is enabled, the scaffolder watches tasks that are in processing. If a worker stops updating a task’s heartbeat and the configured stale period expires, Backstage changes the task back to open so a worker can resume it. The documented default for scaffolder.taskRecovery.staleTimeout is 30 seconds.
On resumption, the task engine starts after the last step that was recorded as complete. It skips completed steps, restores their outputs for later steps, and keeps task secrets until the task reaches a terminal state. The v1.55.0 release notes summarize the contract: “A new scaffolder.taskRecovery config section enables automatic recovery of scaffolder tasks that crash or time out.”
Popular on Amazon
- 【90 Degree Full Function USB C Adapter】Supports the latest USB4 standard for up to 40Gbps of bandwidth, 8K video support, and up to 240W Fast charging; Support USB PD 3.1 Extended Power Range (EPR) including 140W, 180W and 240W. Your productivity is easily doubled. *Warm Tip: For the best fit, please make sure the USB-C port is fully exposed; thick or bulky cases may affect compatibility.
- 【Reliable Quality】Made from high-quality, scratch-resistant aluminum alloy, delicate metal frame. get excellent wear resistance and heat dissipation. Non-Slip Design for easier insertion and removal.
- 【Small and portable】Ultra thin size, ultra compact design, a petite physique that matches the minimalist design of your modern laptops. Coming with a slim figure that won't block the port next to the one it's plugged into.
- 【Compatibility】Widely work with most usb c, thunderbolt 4/3 devices. Compatibilit for ROG Ally, Steam Deck, Switch, MacBook Pro, Quest 3 VR headset, Surface Book 2, iPhone 18/17/16/15, Samsung Galaxy S23/S22/S21, Note 20/10, Google Pixel, ChromeBook, etc.
- 【Excellence Customer Support】If you experience any issues or cable failure, simply reach out to our dedicated customer service team. We provide a prompt response within 18 hours, providing you with the necessary technical support to resolve any concerns.
The sequence is therefore:
- A task is running and remains in
processing. - The worker crashes, is redeployed, or times out before finishing.
- Its heartbeat becomes stale (30 seconds by default).
- Recovery moves the task to
open. - A worker claims it and resumes from the last completed step.
- Stored outputs and secrets are available to the remaining steps.
The feature is a forward continuation mechanism. It does not automatically undo a resource that an earlier action created, and it does not promise that a failed business operation can be retried safely without changes to the action.
When should I enable scaffolder.taskRecovery?
Enable it when workers can be restarted or scaled while templates are running and losing an in-flight task would cost more than rerunning its unfinished work. Typical examples include long-running templates, deployments that routinely replace backend pods, and workflows that call rate-limited or intermittently unavailable services.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Before enabling it globally, verify four conditions:
- Repeatable side effects: every action that could be entered again is naturally idempotent, or its external call is inside a checkpoint.
- Secret-retention policy: your security policy accepts keeping task secrets until
completedorfailed. The current guide does not promise automatic token refresh. - Workspace requirements: templates that depend on generated files have a provider configured and sized for their workspaces.
- Operational ownership: someone monitors stale tasks, provider capacity, and duplicate-object errors after rollout.
Use a longer stale timeout if legitimate actions can take more than 30 seconds without the worker writing a heartbeat. The documentation does not publish a heartbeat write interval or recovery-loop polling interval, so do not infer responsiveness from an undocumented number.
How do I configure recovery in Backstage?
Start with the stable global switch. The following is the minimum configuration; the timeout line is optional because 30 seconds is the default.
scaffolder:
taskRecovery:
enabled: true
staleTimeout: { seconds: 30 } # Optional; defaults to 30 seconds
This makes all tasks eligible for recovery. You do not need to add a recovery block to each template. The software-template configuration guide states that the per-template spec.EXPERIMENTAL_recovery field is no longer required.
If the template writes files that must be available after a worker restart, select a workspace provider too:
scaffolder:
taskRecovery:
enabled: true
staleTimeout: { seconds: 30 }
workspaceProvider: database # or gcpBucket
enabled controls task-state recovery, secret retention, and step/output restoration. workspaceProvider is a separate choice that controls workspace serialization. Setting only enabled: true does not preserve the task’s filesystem.
Also popular on Amazon
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
How do I install and register a workspace provider?
The provider must be installed, registered, and selected. Backstage rejects a configured provider that is not installed and registered.
For the development database provider, add the module from the backend package:
Recommended Free Tools
yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-workspace-database
backend.add(
import('@backstage/plugin-scaffolder-backend-module-workspace-database'),
);
For Google Cloud Storage, install and register the GCP module:
yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-gcp
backend.add(
import('@backstage/plugin-scaffolder-backend-module-gcp'),
);
Then configure the bucket provider and its bucket name:
scaffolder:
taskRecovery:
enabled: true
workspaceProvider: gcpBucket
gcsBucket:
name: my-scaffolder-workspaces
The GCP option requires workload identity. The named providers in the current guide are database and gcpBucket; release notes also allow a similar external provider implemented as a module, but do not present S3 as a built-in provider in the current configuration page.
What is the difference between the database and gcpBucket workspace providers?
Choose the database provider for local development and small workspaces; choose gcpBucket (or another approved external module) for production-scale persistence.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →| Provider | What it stores | Limits and prerequisites | Recommended use |
|---|---|---|---|
database |
Workspace snapshots in the Backstage database | 50 MB limit; install the database workspace module. The module migrates legacy database snapshots on first startup. | Development and small workspaces; not recommended for production. |
gcpBucket |
Workspace snapshots in a Google Cloud Storage bucket | Install the GCP module, register it, configure gcsBucket.name, and use workload identity. |
Documented production choice for larger or business-critical workspaces. |
The 50 MB limit and development-only guidance come from the Backstage 1.55.0 release notes and the configuration guide. Workspace-provider extension points remain an alpha API even though task recovery itself is stable, so account for that API status in upgrade planning.
Why did a scaffolder action run twice after recovery?
A step can execute twice when its external operation succeeded but the worker stopped before the step and its workspace were recorded as complete. Recovery then sees an incomplete step and runs it again. Backstage explicitly warns that recoverable actions must be idempotent.
Also popular on Amazon
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Idempotency means repeating the action produces the same final state as running it once. For example, an action that creates a named object should first look up that name or use a deterministic identifier, then update or reuse the existing object instead of creating a second one. Repository creation, cloud provisioning, and permission grants are especially risky if they are implemented as unconditional “create” calls.
When an operation cannot be made naturally idempotent, wrap the successful side effect in a checkpoint:
const res = await ctx.checkpoint?.({
key: 'create.projects',
fn: async () => {
const projectStgId = createStagingProjectId();
const projectProId = createProductionProjectId();
return { projectStgId, projectProId };
},
});
According to the Writing Custom Actions guide, the task engine checks whether a checkpoint with that key already succeeded. If it did, the callback is skipped and its stored value is returned. The key must be unique within the task. If you change the callback’s return type, change the key as well (for example, from create.projects to create.projects.v1); reusing a key with an incompatible value can make a restarted task fail.
This behavior is intentional. The BEP-0004 design states that actions are not considered idempotent by default and that Backstage will not “magically” provide idempotency. Recovery supplies a resume point; action authors supply safe repeat behavior.
How do I persist the scaffolder workspace across restarts?
Install and register a workspace module, select it under scaffolder.taskRecovery.workspaceProvider, and configure its storage. Without that selection, Backstage persists task state, outputs, and secrets but not the files in the workspace.
- Decide whether the workspace is development-sized or production-critical.
- Install the matching module in
packages/backend. - Register the module with
backend.add(import(...)). - Set
workspaceProvidertodatabaseorgcpBucket. - For GCS, set
gcsBucket.nameand configure workload identity. - Restart the backend and confirm startup succeeds; an uninstalled provider is rejected.
- Check that the largest template workspace fits the provider’s limit and retention policy.
Workspace serialization is the difference between “resume the step graph” and “resume the step graph with its files.” A template that downloads an archive, edits files, and then publishes them needs the second behavior if the worker can disappear between those steps.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteHow do I resume a scaffolder task after a restart or crash?
With recovery enabled, there is normally no special operator command: wait for the stale heartbeat threshold, then let a scaffolder worker claim the reopened task. The task should move from processing to open and continue after its last completed step.
For an interrupted task, verify the following in order:
Also popular on Amazon
- Portable and powerful USB-C HUB: BENFEI USB Type-C HUB, with super-soft and knot-free silicone woven design cable, meets most mobile office needs. Compact, lightweight, stylish, and powerful portable USB C Hub equipped with 1 x HDMI port, 1 x 100W charging, and 3 x USB ports. 18-month warranty, 24-hour response, to ensure you feel at ease when using our product.
- Design centered on comfort and reliability: Thanks to BENFEI's end-to-end in-house cable production capability, in-house PCBA and assembly capability, using the industry's most advanced silicone woven design and process, 20cm cable in length, no knots, super-soft, the HUB is easy to use in all scenarios: laptop, tablet, stand etc. Super-soft, 25000+ life cycles, to meet your daily carrying and office needs.
- 100W Charging: Support up to 90W USB C pass-through charging via Type-C port to keep your laptop powered. 10W is reserved for other interface operations. No data and video function on the Type-C port.
- 4K HDMI Display: The HDMI port supports media display at resolutions up to 4K 30Hz, keeping every incredible moment detailed and ultra vivid. Please note that the C port of the Host device needs to support video output.
- Transfer Files in Seconds: Transfer files and from your laptop at speeds up to 10 Gbps with USB A 3.2 port. Extra 2 USB A 2.0 ports are perfectly for your keyboards and mouse.
- Confirm the backend is running the scaffolder backend package (it is included by default in an app created with
npx @backstage/create-app). - Check effective configuration for
scaffolder.taskRecovery.enabled: true. - Confirm the task was interrupted while
processing, rather than deliberately failed or completed. - Allow at least the configured stale timeout to pass.
- Inspect task logs and status for the transition back to
open. - Verify that the next action can read prior step outputs and, when configured, the serialized workspace.
- If an action fails again, inspect its idempotency and checkpoint key before manually rerunning it.
The feature addresses crash, restart, and timeout interruption. It is not documented as a general undo function or as proof that a remote API call that timed out did not succeed.
Do I still need EXPERIMENTAL_recoverTasks and EXPERIMENTAL_recovery?
No for new stable configuration: use scaffolder.taskRecovery.enabled. The old experimental settings remain supported as deprecated fallbacks, but the Experimental Features page says task recovery has been promoted to stable and those fallbacks will be removed in a future release.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →| Legacy setting | Stable setting |
|---|---|
scaffolder.EXPERIMENTAL_recoverTasks |
scaffolder.taskRecovery.enabled |
scaffolder.EXPERIMENTAL_recoverTasksTimeout |
scaffolder.taskRecovery.staleTimeout |
scaffolder.EXPERIMENTAL_workspaceSerialization |
scaffolder.taskRecovery.workspaceProvider |
scaffolder.EXPERIMENTAL_workspaceSerializationProvider |
scaffolder.taskRecovery.workspaceProvider |
scaffolder.EXPERIMENTAL_workspaceSerializationGcpBucketName |
scaffolder.taskRecovery.gcsBucket.name |
Remove per-template spec.EXPERIMENTAL_recovery blocks as you migrate. The current guide says: “When taskRecovery.enabled is set to true, all tasks are eligible for recovery.” If you still use legacy workspace serialization, install and register the corresponding provider; the database module migrates existing legacy snapshots at first startup.
What changed from the old startOver behavior?
The 2024 experimental tutorials described a per-template startOver strategy that restarted the entire template. That is historical setup, not the current stable operating model. Stable recovery is a global opt-in and resumes after the last completed step.
Older API text still describes an optional EXPERIMENTAL_strategy whose default none marks a processing task as failed. That generated reference reflects the legacy field and should not override the current configuration guide when you are deciding how to enable recovery today. A 2024 tutorial that requires spec.EXPERIMENTAL_recovery and startOver should be treated as migration material, not a current recipe.
Is task recovery the same as retrying one failed step or rolling back resources?
No. Automatic stale-heartbeat recovery handles a worker interruption; it does not guarantee a UI control that retries only a logically failed step, and it does not undo resources already created.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsThe original task-retry issue asked for both crash recovery and manual restart from the last failed step. Backstage 1.55 delivers the crash/timeout portion. The configuration guide says completed steps are skipped on retry when recovery is enabled, but current release notes do not define the exact UI states or controls for a manually failed task.
Rollback is a separate, provisional design in BEP-0006. Do not describe that proposal as a shipped recovery strategy or assume Backstage will delete a cloud resource after a later step fails.
Also popular on Amazon
- 【Read before You Buy】 Note: This adapter is USB 2.0 version and cannot transmit HDM, VGA, or other video signals. Nevertheless, they are fully capable of charging devices,duplicating files, and can be seamlessly integrated with USB-C earphones, wireless network adapters, and SD card adapters.
- 【Easy to Use and Safe】Thanks to modern manufacturing techniques, we've made these adapters sufficiently compact so that they can remain inserted in your device without noticeable protrusion or inconvenience. This means you don't have to constantly plug and unplug them, reducing the likelihood of wear and misalignment, and making them more convenient to carry around.
- 【Reliable Quality】Engineered for enhanced durability, durable aluminum alloy shell material,get excellent wear resistance and heat dissipation,the male USB C and female USB connectors & the male USB and female USB C connectors are designed to be plugged and unplugged up to 20000 times. Provides data transfer, device charging, memory space expansion, and additional computer peripherals.
- 【Think more for you】Do you need to connect a USB-C-enabled device to an odd device that only has USB-A ports? Then these USB-A male to USB-C female adapters are made for you.Simply insert the adapter into the USB-A port on the device, and you can instantly connect your USB-C device to the device that originally didn't have the correct connection port.
- 【Trusted xiwxi Quality and Service】As a responsible brand seller, you will receive xiwxi's 12-month Quality assurance and lifetime friendly customer service, you're not just buying a product,you're investing in peace of mind with all-round quality and exceptional customer service.
What are the main operational pitfalls?
Most incidents come from confusing task-state persistence with workspace persistence, or from repeating a non-idempotent side effect.
- Duplicate resources: make create operations deterministic, lookup-before-create, or checkpointed.
- Missing files: configure a workspace provider;
enabled: truealone does not save files. - Provider startup failure: install and register the selected module before setting the provider key.
- Database overload: keep database workspaces below 50 MB and out of production.
- Expired credentials: secrets are retained until a terminal state, but the current docs do not promise refresh. Design actions to obtain valid credentials when they run.
- False expectations about timing: 30 seconds is the default stale threshold, not a published heartbeat or scan interval.
- Legacy configuration drift: migrate deprecated
EXPERIMENTAL_keys and remove old per-template recovery blocks.
What is a sensible production configuration?
A typical production baseline is enabled: true, an explicitly chosen stale timeout, workspaceProvider: gcpBucket, the registered GCP module, workload identity, and a bucket sized for the largest workspace. Keep every recoverable action idempotent or checkpointed, and test failure paths in a non-production environment before enabling the flag for all templates.
Use the database provider for local development or small workspaces under its 50 MB limit. If a template does not use files at all, you may not need workspace serialization, but you still need idempotency because task state can resume an incomplete action.
Backstage 1.55.0 introduced the stable configuration on September 15, 2026. The living configuration and backend documentation read in November 2026 remain the operator contract; later patch notes cited for that release series address other areas and do not change the recovery behavior described here.
Frequently Asked Questions
Can task recovery resume if the worker moves to another Backstage instance?
Yes, provided the task state is shared and, when files are required, the workspace is serialized through a configured provider. Without a provider, the new worker can restore step outputs and secrets but not the previous worker’s filesystem.
Are task secrets deleted immediately when recovery finishes a step?
No. The documented behavior keeps secrets until the task reaches completed or failed. Treat that retention period as part of your security and storage policy.
Free tools Windows power users keep installed
One-click scans. No signup required.
What happens if a task is processing when I disable recovery?
The stable documentation defines behavior when recovery is enabled; it does not promise a migration or repair action for tasks already stale when you turn the flag off. Inspect and handle those tasks using your normal failed-task procedures before changing the setting.
Does a 30-second stale timeout mean a task is dead after exactly 30 seconds?
No. Thirty seconds is the default threshold for a stale heartbeat. Backstage does not publish the worker heartbeat write interval or the recovery-loop polling interval in the cited operator documentation, so actual pickup time can be longer.

