How can I troubleshoot a deployment failure for an AWS IoT Greengrass component that runs a Docker container?

2 minute read

My component that runs a Docker container failed to deploy on AWS IoT Greengrass Core Version 2, and I want to resolve the error.

Short description

When an AWS IoT Greengrass component that runs a Docker container fails to deploy, the error is typically caused by a permissions issue.

The following is an example error message for a component deployment failure:

com.example.RaspberryDockerComponent: stderr. permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/images/load?quiet=1": dial unix /var/run/docker.sock: connect: permission denied. {, serviceName=com.example.RaspberryDockerComponent, currentState=NEW}


To successfully deploy an AWS IoT Greengrass component that runs a Docker container, change one of the following permissions:

  • (Best practice) Configure the Docker container to run for non-root or non-administrator users.
  • Grant root or administrator permissions to the user who deploys the component.

When a user gets a permission denied error, an administrator user must add the user to the Docker group. As a member of the Docker group, the user can run commands without administrator privileges.

To add user permissions, complete the following steps:

  1. To add ggc_user to the Docker group, run the following command:

    sudo usermod -aG docker ggc_user

    Note: In your command, replace ggc_user with your non-root user.

  2. To restart AWS IoT Greengrass to apply the user permissions updates, run the following command:

    systemctl restart greengrass
  3. Redeploy the component, and then verify that the user can run commands.

Related information

Run a Docker container

AWS OFFICIALUpdated a year ago