Troubleshooting activity packages

Fix the common problems of building, installing and running a custom activity package, from restore and pack errors to an empty toolbox and failed Robot restores.

Where to look# Build problems: the dotnet pack output. Every check prints a code, the activity concerned and the fix. Look the code up in the Reference. Studio problems: the Output panel, Packages channel, and the project's Dependencies node in the Explorer. Robot problems: the job's error and log in the Orchestrator, and the Robot's logs. See Robot logs and troubleshooting. Building# Symptom Cause and fix No templates or subcommands found matching: 'velophex-activity' The template is not installed for this user. Run dotnet new install VeloPhex.ActivityPackage.Templates and check with dotnet new list velophex. Restore fails with NU1101: Unable to find package Velophex.Workflow.Sdk (or VeloPhex.ActivityPackage.Build, VeloPhex.Platform.*) No package source serves the VeloPhex SDK packages. Add the feed to nuget.config, and if you use package source mapping, map VeloPhex.* to it. See Set up your environment. The type id prefix '...' is reserved for VeloPhex's own packs VelophexTypeIdPrefix is velophex or starts with velophex.. Choose your own prefix in Directory.Build.props and in your [ActivityType] ids. NU5104 Your package has a stable version but depends on a prerelease SDK. Use a prerelease version, such as 1.0.0-preview.2. VXMAN008: ... names icon 'X' but the package ships no icons/X.svg Add icons/X.svg beside the runtime project's source, or fix the IconKey. VXMAN013 Start PackageReleaseNotes with the version being packed: $(Version): .... VXPKG051: ... declares 'Timeout' Rename the argument (for example TimeoutSeconds). The engine provides Timeout and Continue On Error on every activity. VXDSN001, VXDSN017 The build tool and the SDK are from different releases. Set the four lines of VeloPhex.Versions.props to the values of one release. VXDSN014 A fluent design needs an assembly the build could not find. Add <VelophexDesignProbeDir Include="..." /> or set VelophexRunDesignAssemblies to false. VXMAN001 mentioning VXMETA003 An activity derives from a base class in another assembly. Derive from an SDK base class or one in the same assembly. Installing in Studio# Symptom Cause and fix The package installs but the toolbox shows none of its activities Check, in order: (1) The package has no activity manifest: it was not packed through the package project with VeloPhex.ActivityPackage.Build (for example, the runtime project was packed on its own). Open the .nupkg and look for velophex/activity-manifest.json; repack from the package project. (2) Studio's engine is older than the package's engineVersionRange (VXPKG016): the Dependencies node shows Could not be loaded. Update Studio, or build against an older SDK release. (3) The activities are Hidden = true. The package does not appear in Browse The source is off, or the package is a prerelease and Include prerelease is off. Check Settings and the filter menu. An activity shows a placeholder instead of its icon The SVG breaks one of Studio's icon rules, most often a transform attribute, a viewBox other than 0 0 24 24, a stroke-only shape or a color outside the allowed palette. The Output panel names the file and the reason. See Icons. A change (a display name, a card property, a new rule) does not show Studio caches design metadata per package version. Give the package a new version, pack, and update the project to it. Repacking the same version never shows the change. A custom dropdown, editor or card body does not appear The design assembly did not run. The Output panel says why: the package is unsigned and its source is not Trusted, the design assembly was built against a newer Velophex.Studio.Sdk than Studio's, or no provider serves the DataSource key (VXDSN007 at pack time). Install fails and the changes are undone A dependency could not be restored. Make sure every dependency, including Velophex.Workflow.Sdk at the version you built against, is available from an enabled source. The package is refused with VXPKG023 or VXPKG024 A file was added or changed after packing. Never edit a .nupkg; pack again. The package is refused although it is fine Its id starts with VeloPhex. or Velophex., which is reserved for packages signed by VeloPhex. Rename your package. Running# Symptom Cause and fix VWF1301 unknown activity type in a workflow that used to work The package is no longer installed, or the activity's type id changed. Type ids are permanent: restore the old id, and retire activities with Hidden = true instead of removing them. A child activity reports that it needs an enclosing scope (VWF1310) Put it inside the scope's Use activity, or bind its Session argument. See Scopes. context.GetService<T>() returns null The service is not offered by this host (some services exist only in a job on a Robot), or your service contributor threw; the run log has a warning about it. Fail with a clear message when a service is missing. GetSecretAsync or ProtectSecret throws NotSupportedException The host keeps no secrets in this context, or the activity does not declare the Credentials capability. ScheduleSlot throws NotSupportedException Container activities run only in the workflow's own process, not in ActivityTestHost or an isolated host. A retry policy does not retry your activity Only activities that are idempotent, retry-safe or replay-safe are retried. Declare [ActivityCharacteristics(RetrySafe = true)] if a retry is safe. BusinessRuleException is never retried. After a Robot restart, a job is suspended waiting for a recovery decision The activity was interrupted and is NonReplayable (the default). Declare Idempotent, [ActivityRecovery(ActivityRecoveryBehavior.ReplaySafe)] or a recovery probe if a rerun is safe. See Characteristics. On Robots# Symptom Cause and fix The job fails while restoring packages (VXPKG031) No feed the Robot uses has the package or one of its dependencies. Add your feed under Tenant ▸ Settings ▸ Package feeds, check its package patterns and credentials, and check that third-party dependencies are reachable. See Publish and install. The job fails with VXPKG016 The Robot's engine is older than your package's floor. Upgrade the Robot, or build the package against an older SDK release. Publishing the automation fails with VXPKG054 The project uses activity packages whose engine ranges no single engine satisfies. Align the packages on one SDK release. The package is refused by trust policy (VXPKG040) The tenant or the Robot requires signed packages. See Signing packages. The activity works in Studio but not on the Robot Compare what differs: the machine's session (a service in session 0 has no desktop), file paths, network access and proxy, and the Robot's account rights. Activities run with the executor's rights on that machine. Next steps# Reference Getting help

Where to look

Building

Installing in Studio

Running

On Robots

Next steps