How to purge malfunctioning workshops

Troubleshooting← Resolve plug conflicts

Workshops can sometimes become unresponsive, encounter errors during start or stop operations, or become orphaned if their project directory is removed prematurely.

A thorough purge involves removing the workshop’s containers, metadata, and files in a deliberate sequence.

Prerequisites

Before starting, ensure you have these requirements satisfied:

  • Identified the workshop and project you intend to purge.

  • Tried workshop remove <WORKSHOP> or confirmed that the standard removal flow cannot be used.

  • Backed up any workshop data you need to keep; manual cleanup can permanently delete containers, metadata, and files.

  • Access to sudo and lxc for manual LXD cleanup.

Standard removal procedure

The primary command for removing a workshop is:

$ workshop remove <WORKSHOP>

This command is designed to:

  • Stop the workshop if it is running.

  • Delete the underlying LXD container.

  • Remove associated workshop data and cache directories.

  • Clean up related LXD profiles and remove device mounts.

Always attempt this command first. If it completes successfully, your workshop should be purged. You can verify the outcome by running workshop list.

If standard procedure fails

You may need manual intervention if:

  • workshop remove fails with an error.

  • The workshop is still listed by workshop list or workshop list --global after a remove attempt.

  • The workshop’s project directory had been deleted before the workshop was removed, leaving the workshop orphaned.

  • The workshop is in an unrecoverable error state.

  • The workshop’s container is still running or in an error state, preventing the standard removal flow from completing.

For an orphaned workshop, first try recreating its project directory, which restores the standard removal flow without touching LXD. In other cases, or if that fails, manually clean up the workshop’s resources, interacting directly with LXD and the workshop’s snap data; start by finding the LXD project.

Remove an orphaned workshop

If a project directory is deleted before its workshops are removed, the workshops become orphaned: their containers and stored state remain on the host, and the daemon reports them in the Error state with a missing-project note:

$ workshop list --global

  PROJECT            WORKSHOP  STATUS  NOTES
  ~/projects/nimble  nimble    Error   missing-project

Commands that resolve the project by its pathname, including workshop remove with the --project option, no longer work for orphaned workshops:

$ workshop remove --project ~/projects/nimble nimble

  error: cannot create or load project at "/home/user/projects/nimble": lstat /home/user/projects/nimble: no such file or directory

However, the daemon keeps tracking the project’s original location, so you can restore the standard removal flow by recreating the directory:

  1. Recreate the directory at the same absolute path; it can remain empty:

    $ mkdir -p ~/projects/nimble

  2. Remove the workshop, pointing at the recreated directory:

    $ workshop remove --project ~/projects/nimble nimble

  3. Verify the removal and delete the recreated directory:

    $ workshop list --global
$ rm -r ~/projects/nimble

Note

Removal isn’t the only option: running any workshop command against the recreated directory re-associates it with the original project, restoring the hidden .workshop.lock file. To recover the workshop instead, restore the project’s content (e.g. from a repository) and continue using it.

Find LXD project

Workshop creates LXD projects named workshop.<USERNAME>, where <USERNAME> is your system username. If the username can’t be used in an LXD project name (e.g. if it contains special characters such as @), your numeric user ID is used instead (id -u). You’ll also need your username for some paths.

Clean up LXD resources

Refer to the Explore LXD containers section in the troubleshooting guide for initial steps on listing and deleting orphaned LXD containers, e.g.:

$ sudo lxc list --all-projects | grep workshop.<USERNAME>
$ sudo lxc delete --project workshop.<USERNAME> <CONTAINER> --force

To ensure there are no backup copies of the workshop remaining, check the workshop-snapshots.<USERNAME> project as well:

$ sudo lxc list --all-projects | grep workshop-snapshots.<USERNAME>
$ sudo lxc delete --project workshop-snapshots.<USERNAME> <CONTAINER> --force

In addition to containers, you may need to clean up associated LXD profiles.

LXD profiles

Workshops create an LXD profile for each SDK they use. These profiles are named <CONTAINER>-<SDK>. If a workshop container wasn’t cleanly removed, its profiles might remain.

  • List profiles for your workshop user project:

    $ sudo lxc profile list --project workshop.<USERNAME>

  • Inspect a specific profile:

    $ sudo lxc profile show --project workshop.<USERNAME> <PROFILE>

  • Delete an orphaned profile. To ensure it’s not in use by other valid workshops, list all containers in the project firstly:

    $ sudo lxc list --project workshop.<USERNAME>

    Then, for each container that should remain, check its configuration to see which profiles it uses:

    $ sudo lxc config show --project workshop.<USERNAME> <CONTAINER>

    Look for the profiles key in the output.

    If the <PROFILE> you intend to delete is not listed for any relevant containers, it should be safe to remove:

    $ sudo lxc profile delete --project workshop.<USERNAME> <PROFILE>

  • To delete an orphaned profile, check the USED BY column in the output of the lxc profile list command. If the count is zero, the profile is not used by any containers and can be safely removed.

Remove leftover host directories

Deleting containers with lxc doesn’t remove the state that Workshop stores for them on the host. This state is keyed by project ID, which is the final dash-separated segment of the container name; for example, ec275767 for a container named nimble-ec275767.

Check these locations for leftover directories, removing them if present:

$ rm -rf ~/.local/share/workshop/id/<PROJECT-ID>
$ sudo rm -rf /var/snap/workshop/current/id/<PROJECT-ID>
$ sudo rm -rf /var/snap/workshop/common/workshop/cache/id/<PROJECT-ID>

Aggressive cleanup

If previous steps haven’t resolved the issue, or if workshop list still shows remnants, the most aggressive cleanup method is to completely purge the Workshop snap. This executes the snap’s remove hook, which is designed to clean up all associated data and resources.

To purge the snap and all its data, run the following command:

$ sudo snap remove workshop --purge

This will remove all workshop configurations, containers, LXD profiles, and storage pools managed by Workshop.

After the command completes, you can reinstall the snap.

Warning

This is a highly destructive operation that removes all workshops for all users on the system. It should only be used as a last resort. You will need to reinstall Workshop to use it again.

Final checks

After performing manual cleanup steps:

  • Run workshop list --global to check if the malfunctioning workshop is no longer listed.

  • Run sudo lxc list --all-projects to ensure no unexpected LXD resources remain.

If issues persist, consider seeking community support, or reporting a bug with detailed logs and steps taken: Project and community.

See also

Explanation:

How-to guides:

Reference: