Why Backstage scaffolder tasks fail and how to find the failing step
A developer starts a new service from a Backstage software template, the run stops partway through, and the platform team has to find the failing step quickly. The scaffolder is the Backstage component that runs a template's ordered actions, such as fetching a skeleton, rendering files, and publishing a repository. Each run is recorded as a task, and the task view shows the output of each step, so the first job is to open that view and identify the step that stopped the run, not to guess from the error message shown to the developer. The Backstage architecture overview places Software Templates among the core built-in features, which is why this troubleshooting depends on the scaffolder's own task records rather than on external tooling.
Teams need this skill whenever a template run fails in a way the developer cannot fix alone: a publish step cannot create a repository, a token lacks permission, a custom action throws, or a run hangs after a partial success. The platform team should confirm, before an incident, who can open task logs, which templates they own, and how the team's Git platform credentials are scoped. Confirm also the Backstage release line and Node.js version in use, because the versioning policy ties supported runtimes to the release, and a failure after an upgrade may come from a changed action rather than a bad template.
This page covers reading step logs in the task view, the publish and permission failures teams meet most often, cancelling a stuck task and re-running it with Start Over, and changes that make failing actions easier to debug. Read the failing step first, then decide whether the fix belongs in the template, the credentials, the action code, or the Backstage configuration. Verify the fix by running the template again against a disposable target, because a re-run that succeeds in a sandbox does not prove the same permissions exist in production. The Backstage architecture overview is the right starting point for how the catalog, templates and TechDocs fit together.
How to read scaffolder step logs in order
This sequence takes a failed Backstage scaffolder task from the first red step to a clear verdict: whether the template, its inputs, or the environment caused the failure. It ends with a support-ready record that someone else can act on without repeating your investigation.
Open the task page and find the failed step
Open the task from the scaffolder task list in Backstage and note its ID, the template name, and the user who started it. Steps run in the order the template defines them, so the first step marked as failed is the one to read; later steps usually show as skipped or never started. Confirm you are looking at the failed step, not the last step that completed, before reading any logs. Done when you have written down the task ID and the failed step's name.
Read the log lines above the error
Expand the failed step and read from the top of its log down to the error line, not only the final message. The lines just before the error usually show which action started, which file, URL, or repository it touched, and what it reported back. Look for the first unexpected line, because later lines are often side effects of that first problem. Done when you can state in one sentence what the step was doing when it stopped.
Check the step inputs against the template parameters
Compare the values the failed step received with the parameters the user entered on the template form. Mismatches often come from a template expression that builds a name, path, or URL incorrectly, such as a missing prefix, a character the target system rejects, or an empty value that was never validated. Check the template's parameter schema for required fields and format rules that should have caught the value. Done when you know whether the input value was what the author intended.
Separate template errors from environment errors
Decide whether the cause sits in the template or in the environment. Template errors reproduce for any valid input and point to the action's code, its parameters, or its expressions. Environment errors depend on configuration such as a missing or expired token, a credential the backend cannot read, a permission the integration account lacks, or a network path that is blocked. Retry with the same valid input on a sandbox repository or target if you can. Done when you have labeled the cause as template, input, or environment.
Confirm credentials and permissions for the failing action
For environment failures, confirm which integration credential the action uses, that it is configured in the backend for this environment, and that its account can perform the action on the target. Ask the platform owner to confirm the token scopes, the account's membership in the target group or organization, and whether the credential has expired or been rotated. Do not paste secret values into the ticket; record only the name of the configuration key and the error text. Done when you know whether the credential exists, is readable, and has the needed permissions.
Capture the evidence for a support ticket
Collect the task ID, template name and version, the failed step name, the input values with any secrets removed, the log excerpt from the lines above the error through the error itself, the Backstage version, and the time of the attempt. Add your labeled cause and what you already checked, so the reader does not repeat it. Confirm the excerpt contains no tokens or personal data before you attach it. Done when another engineer could reproduce or route the issue from the ticket alone.
Which publish and permission failures appear most often
Most failed scaffolder runs that reach the publish step come from a short list of causes: the Git host rejecting the push, a credential that lacks scope, a repository that already exists, a template owner without rights, catalog registration after publish, or a custom action that throws. The cards below are ordered from the publish step outward, so you can start with the step that failed in the task log and work toward the cause.
Publish step rejected by the Git host
The publish action creates a repository and pushes the rendered skeleton, and the Git host can refuse either call. Check the failing step's log for the host's response to the create-repository request, then confirm the target organization, namespace or project exists and the template points at the right host and URL. Confirm the host integration in the app configuration matches that same host. A mismatch between the template's target and the configured integration is a frequent cause and is quick to test.
Token or credential scope problems
The integration token that the scaffolder uses for publishing must carry the scopes needed to create repositories and push content in the target namespace. A token that reads fine but cannot create repositories will pass catalog reads and still fail at publish. Check which account owns the token, whether it has expired or was rotated without updating the secret the backend reads, and whether the namespace requires a different scope than the one granted. Use a token owned by a service identity, not a personal account, so the publish does not break when someone leaves.
Repository already exists
Templates that build names from a component name or owner field collide with repositories created earlier, either by a previous run or by a team working outside the portal. Review the template's repository name parameter and the naming rule the Git host enforces, then search the target namespace for the name the run tried to create. If an earlier run created the repository and then failed later, decide whether to reuse, rename or delete it before running again, because a rerun that assumes a clean slate will fail at the same point.
Permission denied for the template owner
Software templates carry access rules that decide who can run them, and the publish step runs under the integration identity rather than the user who clicked the button. A user who can open a template may still lack the permission to run it, or the template may reference a group that no longer exists in the directory. Check the authorization policy for the template, confirm the user's group membership in the catalog, and verify the owner reference on the template entity points to a group that exists.
Catalog registration failing after publish
The repository can be created and pushed successfully, then the registration step fails because the new catalog-info file is not yet discovered or does not validate. Check the registration step's log for the location it tried to add, confirm the default branch the registration read matches where the publish pushed the file, and inspect processing errors on the new entity. The repository may exist and be usable even though the portal has no record of it, so resolve the catalog side before you rerun the whole template.
Custom action errors
Custom actions written for your organization run inside the scaffolder backend and fail for reasons the built-in actions do not, such as an unhandled exception in input parsing, a missing environment variable, or a call to an internal API that now returns an error. Find the action's name in the failing step, read its output and any thrown message, and reproduce its inputs in a test before changing the template. Add explicit input validation and clear error messages inside the action so the next failure names the cause in the step log.
Cancelling, re-running and using Start Over safely
A task that is still running and should not finish needs to be stopped before anything else. Scaffolder steps run in order, so a task can be partway through creating a repository, pushing files or registering a component when someone notices the wrong inputs were submitted. Stop it first, then decide what to keep. Do not start a second run while the first is still writing to the same repository or cloud account, because two runs can race each other and leave conflicting files or duplicate resources.
- Find the task ID: Open the task from the scaffolder task list in the portal, or note the ID shown on the task page, so you can match it against the logs and the step that is executing.
- Check the last completed step: Read the step log to see which actions have already succeeded, since those are the actions that created external state.
- Confirm the cancellation behavior in your version: Check the scaffolder documentation and release notes for the Backstage version you run, because cancellation support and what it guarantees for in-flight external calls can change between releases.
- Inspect external systems before continuing: Look at the Git host and any cloud or ticketing systems the template touched, because a stopped task does not undo calls that already completed.
- Record what you stopped: Note the task, the inputs and the step reached so the next run or the cleanup has a clear starting point.
Before you re-run anything from this tab, confirm the task has reached a stopped state and that no step is still writing to external systems.
Some failures come from outside the template: a Git host returns a rate limit, a cloud API times out, a token expires mid-run or a network path drops. These failures often do not reflect a mistake in the template, so a retry is usually the right move once the external condition has cleared. Before retrying, though, check which steps already succeeded. A publish step that reported a timeout may have created the repository anyway, and a second run that assumes it did not will fail on the name collision or create a second copy under a slightly different name.
- Read the failing step's error: Distinguish an authentication or throttling error from a schema or input error, since only the first group is likely to clear on its own.
- Verify the external state: Check whether the repository, project or resource exists and what it contains before you choose a retry path.
- Confirm the credential: Make sure the integration token or app credential is still valid and has the scopes the publish action needs, because an expired token is one of the most common causes of a failed publish.
- Retry after the cause clears: Use Start Over only when the external state matches what the task expects, or clean up the partial result first.
- Watch for repeated failures: If the same external error returns after a retry, treat it as a platform or network problem rather than a transient one and escalate it.
Before retrying, confirm that the external system state matches the step the task failed on, not the step you hope it reached.
A task that fails because the template or inputs were wrong will fail the same way on every retry, so re-running without a change only repeats the failure and may leave more partial resources behind. Fix the cause first. The cause might be a parameter that does not match the schema, a skeleton file that references a variable that is never set, a publish action pointed at the wrong owner or an action that expects an output from a previous step that never ran. Work out whether the failing step is the first step that does external work, because if earlier steps already created resources, those need cleanup before a new run.
- Separate the template from the inputs: Compare the submitted values against the template parameters to see whether the failure comes from bad input or from a template defect.
- Fix the template in a branch: Test template changes against a non-production Git owner or sandbox namespace, so a corrected run does not collide with the failed attempt.
- Remove partial output: Delete or archive repositories, projects or registrations left by the failed run, following your own cleanup process, before starting over.
- Confirm Start Over behavior: Check how the Start Over option in your installed scaffolder version reruns the task, including whether it reuses the original inputs and whether it reruns from the beginning, so you know what state it will meet.
- Add checks where the failure was silent: If a bad input passed validation and failed late, add an earlier validation step or clearer error message, which the debugging guidance for failing actions can help with.
Before starting over, confirm the corrected template and inputs have been tested and that every resource left by the failed run has been removed or deliberately kept.
Making failing custom actions easier to debug
The fastest way to shorten a scaffolder diagnosis is to make each custom action explain itself. Log with context, not just with success or failure. Inside the action handler, use the logger that the scaffolder passes into the action context, and record the step name, the key input values (with secrets removed), and the identifier of the remote object the action touched, such as a repository name or merge request number. A message like "creating repository" tells an operator nothing when the step fails, while a message that names the target and the response status points straight at the cause. Confirm how the logger is exposed and how its output appears in the task log for the Backstage version you run, because the context object and logger methods have changed across releases and the current Backstage documentation for custom actions is the reference to check.
Validate inputs before the action makes any remote call. Define the input schema with the schema support the action API provides, and where a value has a format rule (a repository slug, a branch name, a DNS-compatible service name), check it in the handler and throw an error that names the field and states the rule that failed. Readable input errors separate template authoring mistakes from platform outages, which is often the first question a platform team has to answer. Make steps idempotent as well: before creating a repository, branch or file, check whether it already exists and whether it matches what the action would create. That way a task that failed halfway can be started again without producing duplicate resources or conflicts. Decide, per action, which side effects are safe to repeat and which need a manual cleanup step, and document that decision next to the action.
Finally, test actions outside a live task. Unit tests that call the handler with mocked clients and a fake logger let you assert on error messages, log lines and the shape of outputs without waiting for a full template run. Keep a small set of integration tests against a sandbox organization for the remote calls that mocks cannot model well, and run them in CI on the same Backstage version your portal uses. When a production task fails, reproduce the failing input in a test first. A reproduction that fails in CI is a far better evidence trail for the platform team and the template owner than a screenshot of a task log.
Questions teams ask before fixing scaffolder failures
Is a failing scaffolder task an internal fix or something that needs outside help?
Most first-line failures, such as a wrong parameter, a missing secret or a template step that points at the wrong branch, are internal fixes that your platform team can resolve from the step logs. Outside help makes sense when failures repeat across templates, when custom actions are written by people who have left, or when the team lacks time to triage. Start by reading the failing step output in the Backstage UI and checking whether the same step fails for every user. If the cause is a permission or publish error that recurs, bring in help sooner, since those usually involve Git platform settings and the scaffolder's backend configuration rather than the template itself.
What makes the effort to fix scaffolder failures larger or smaller?
Effort is driven mainly by three things: the number of custom actions, the number of Git platforms the templates publish to, and the permission model that decides who can run which template. A portal with two templates that publish to one Git host is a small job. A portal with many custom actions that call internal APIs, several Git platforms with different token scopes, and group-based access rules takes longer, because each failure needs its cause isolated across the template, the action and the integration. Ask for an inventory of custom actions and their owners, the Git platforms in use, and a description of how access to templates is granted before requesting a quote.
What does the work need from our team to get started?
Plan for access to the portal's backend logs, the scaffolder task history for the failing runs, and the repository where templates are stored. For publish failures, someone with Git administrator rights on the target organization needs to confirm token scopes, branch protection and repository creation rules. A sample template that reproduces the failure is the single most useful input, along with the version of Backstage in use and the configuration files, with secrets removed. Your team should also name one person who can approve changes to templates, because fixes usually involve a small template edit that needs review.
Can our own team fix scaffolder failures without a partner?
Yes, if at least one engineer can read TypeScript, understands the Backstage scaffolder's step model and has access to the logs and Git settings listed above. The common path is to re-run the task after a fix, use the step logs to find the failing action, and add logging to custom actions so the next failure is easier to read. Teams usually struggle when no one owns the custom actions, when the Git token belongs to a departed employee, or when permission rules were set up without a written record. Those gaps are where a partner adds the most value, and they are also what your team should check first.
Will restarting or re-running a failed task repeat the same error?
It can, because a re-run uses the same template parameters and the same configuration. Backstage lets you cancel a running task and start over from the scaffolder UI, but that does not change the root cause. Before re-running, confirm the fix is in place: the token has the needed scope, the target repository name is free, or the custom action has been corrected and deployed. Keep a note of which tasks were re-run so you can tell whether a fix worked. If a task creates partial resources, such as a repository that exists but has no content, check and clean those up manually before starting over.
How is a fixed-scope engagement for scaffolder troubleshooting agreed?
Most DeployOpen engagements are fixed-scope, so the scope, deliverables and timeline are written down and agreed before work starts. For a scaffolder troubleshooting job, the written scope usually lists the templates and custom actions in scope, the Git platforms covered, the failure cases to resolve, the verification steps and the handover material. A quote follows from that written scope, so the more precise your inventory of templates, actions and access rules, the more accurate the quote will be. DeployOpen does not publish a price list. Ask for the assumptions and exclusions to be written out, including what happens if new failure cases appear during the work.
Does a fix to a scaffolder failure touch security or access rules?
Often yes. Scaffolder tasks run with credentials for Git platforms and other systems, so a publish failure can point to a token that is over-scoped, expired or stored in the wrong place. Review who can run each template and which secrets the actions read before changing anything. Any change to token scopes or template permissions should be recorded so it can be reviewed later. The Backstage authentication documentation advises that sign-in resolves every provider to the same identity, which also affects who is allowed to run a template.
Security checks while debugging scaffolder runs
Scaffolder runs touch Git tokens, user inputs and task history, so debugging a failure can expose secrets or widen access if you are careless. The cards below are checks to run while you troubleshoot, covering what appears in logs, which tokens publish steps use, how sign-in is configured for the people who trigger runs, and who can re-run or cancel tasks.
Scan logs and inputs for credentials
Step logs and the task parameters shown in the UI are the first places a token or password can leak during debugging. Before you paste a log into a ticket or chat, search it for strings that look like tokens, connection strings and private keys, and check whether any template parameter was filled with a secret. Confirm that your custom actions do not print the full options object or the token value when they fail. If a secret appears, rotate it, because it should be treated as exposed once it has been shown in a log.
Give publish steps least-privilege tokens
The publish step usually creates a repository and pushes to it, which tempts teams to reuse a broad personal or organization token. Check which account and scopes the integration token carries for each Git platform, and limit it to creating repositories in the target namespace. Confirm the token cannot administer other repositories or read unrelated organizations. Also check that the token is set through your secrets configuration and not written into a template or a committed config file.
Confirm guest access is off
The authentication guidance advises against offering guest access in production, because a guest identity cannot be traced to a person who should be running templates. While debugging, confirm that the production configuration does not enable the guest provider, and that every person who can start or re-run a task signs in through a configured provider. Check that the sign-in resolver maps each provider to the same catalog user, so that a task history entry can be tied to one accountable identity.
Audit who can re-run or cancel
Start Over and cancel actions change live state, such as creating repositories or registering components a second time. Review which groups hold the permissions that allow a task to be re-run or cancelled, and compare that list with who actually operates the portal. Export or review the task history to see who triggered each run, and flag any run started by a shared or unidentified account. Confirm that permission policies apply to the scaffolder actions you expect them to cover.
Check custom action outputs
Custom actions often log their inputs during development and forget to remove that logging before production. Review each action your template uses and confirm it does not write credentials, personal data or full request bodies to the task log. Also check that error messages do not echo headers returned by the Git platform, since those can include tokens or session identifiers. Repeat this review after each change to an action, because a new debug line can reintroduce the exposure.
How DeployOpen works on this
DeployOpen approaches failed Backstage scaffolder tasks as a scoped piece of work on your own Backstage instance, inside your infrastructure. We start from the task logs and the templates involved, then agree in writing what gets fixed, tested and handed over before any change is made.
How we scope
- Written scope lists which templates, actions and Git publish targets are covered by the fix.
- We review step logs, task history and the template files with your platform team before estimating the work.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
How we build
- Fixes to failing actions are built in your own repository and reviewed through your normal change process.
- Permission and publish problems are reproduced in a non-production instance before any production change.
- Actions get clearer logging and error messages so future failures show the failing input and step.
How we hand over
- You receive the code changes, a short runbook for reading step logs and re-running tasks, and a list of known limits.
- Test cases cover the templates in scope, so your team can confirm a fix still works after upgrades.
- Knowledge transfer sessions walk your engineers through the diagnosis steps used on the engagement.
How we support
- Ongoing support for scaffolder issues is available as a retainer, scoped to your templates and plugins.
- Retainers can include monitoring of failure patterns and review of Backstage release changes that affect actions.
- Ask for the support scope, response expectations and update process in writing before you sign.
