Driver FixRecommendedSound, Wi-Fi or graphics acting up? Check drivers firstFind missing or outdated drivers fast.Check DriversThanksgiving DealsAmazon USThanksgiving week: Black Friday picks start earlyAmazon US: current deals, useful picks and tech finds.Check DealsClean PCRecommendedOne scan can reveal what keeps slowing WindowsLook for cleanup and repair opportunities.Run Scan×
FREEDOM251

Freedom251 › Blog

Backstage Scaffolder Task Recovery: How It Resumes Work and When to Enable It

By Freedom251 Team · · 10 min read

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

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
Sale
Silkland 40Gbps USB C 90 Degree Right Angle Adapter 2 Pack, 240W USB4 | Male to Female Extender, 8K@60Hz, Thunderbolt 4/3, Steam Deck, ROG Ally, MacBook, Switch 2, iPhone 18/17/16/15, Quest 3 VR
  • 【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:

  1. A task is running and remains in processing.
  2. The worker crashes, is redeployed, or times out before finishing.
  3. Its heartbeat becomes stale (30 seconds by default).
  4. Recovery moves the task to open.
  5. A worker claims it and resumes from the last completed step.
  6. 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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

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 completed or failed. 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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

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
Sale
Anker USB C Hub, 5-in-1 USBC to HDMI Splitter with 4K Display | 85W Max PD, 1 Powered USB-C 5Gbps & 2 Powered USB-A 3.0 5Gbps Data Ports, for MacBook Pro, MacBook Air, Dell and More (Black)
  • 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:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
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
Sale
Anker USB C Hub, 7in1 Multi-Port USB Adapter, 4K@60Hz USBC to HDMI Splitter | 85W Max PD, 2 USB 3.0 & 1 USBC Data Ports, SD/TF Card Reader, for Laptops/Mac and Other Type C Devices (Charger Not Included)
  • 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:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
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.

  1. Decide whether the workspace is development-sized or production-critical.
  2. Install the matching module in packages/backend.
  3. Register the module with backend.add(import(...)).
  4. Set workspaceProvider to database or gcpBucket.
  5. For GCS, set gcsBucket.name and configure workload identity.
  6. Restart the backend and confirm startup succeeds; an uninstalled provider is rejected.
  7. 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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

How 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
Sale
BENFEI USB C Hub 5-in-1 with 4K HDMI(Certified), 100W Power Delivery, 3 USB-A, Silicone Cable, Aluminum Case Compatible with MacBook Pro/Air, iPad Pro, iMac, iPhone 15 Pro/Pro Max, XPS, Thinkpad
  • 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.
  1. Confirm the backend is running the scaffolder backend package (it is included by default in an app created with npx @backstage/create-app).
  2. Check effective configuration for scaffolder.taskRecovery.enabled: true.
  3. Confirm the task was interrupted while processing, rather than deliberately failed or completed.
  4. Allow at least the configured stale timeout to pass.
  5. Inspect task logs and status for the transition back to open.
  6. Verify that the next action can read prior step outputs and, when configured, the serialized workspace.
  7. 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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
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.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The 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
𝟒𝐏𝐚𝐜𝐤 𝐔𝐩𝐠𝐫𝐚𝐝𝐞𝐝 USB to USB C Adapter,Type-C Female to A Male Charger Converter for iPhone 18 Charger,iWatch Ultra SE 9 10,iPhone 17 Pro Max 16 15 14,Samsung S25,AirPods,iPad,Car,Xbox
  • 【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: true alone 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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

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.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply. Prices as of November 23, 2026 1:31 am GMT+0530.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Crashes, No Sound, or Screen Glitches?Free driver scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.