Greengrass Troubleshooting

Solutions for common issues encountered during Greengrass device setup, connection, deployment, and operation. Start with the symptom you’re experiencing and follow the diagnostic steps to resolution.

Device not Connecting

Symptom: Device remains in “Released” or “Disconnected” status after running the installer.

Diagnostic Steps:

Check service status: Run systemctl status greengrass-lite.target — if the service is not running, the installer may not have completed successfully.

Check internet access: Run ping 8.8.8.8 and nslookup iot.us-east-1.amazonaws.com — DNS resolution must work.

Check port 8883: Run openssl s_client -connect iot-endpoint:8883 — MQTT over TLS requires port 8883 outbound. Corporate firewalls often block this.

Check logs: Run journalctl -u greengrass* --since "5 minutes ago" — look for connection refused, certificate errors, or timeout messages.

Check bundle integrity: Ensure the zip was not corrupted during transfer. Re-download and re-transfer if unsure.

Common Causes:

Cause	Solution
Firewall blocking port 8883	Allow outbound TCP on port 8883 to .iot..amazonaws.com
Wrong bundle used (different device)	Download the correct bundle for THIS specific device
Clock skew on device	Sync time: `sudo timedatectl set-ntp true`
Installer ran as wrong user	Run installer as root or with sudo
Bundle already used (reinstall)	Clean up first: stop service, remove /var/lib/greengrass, then re-run

Certificate Errors

Symptom: Logs show “certificate verify failed”, “handshake failure”, or “unable to get local issuer certificate”.

Common Causes and Solutions:

Device clock is wrong: Certificates have validity periods. If your device clock is set to 1970 (common on first boot), TLS handshake will fail. Fix: sudo date -s "2026-06-26 08:00:00" or enable NTP.

Root CA missing: The AmazonRootCA1.pem must be present. Re-extract from the bundle zip.

Certificate revoked: If you deleted and recreated the device in the portal, old certificates are invalid. Download a fresh bundle.

File permissions: Certificate files must be readable by the greengrass service user. Check: ls -la /var/lib/greengrass/certs/

Deployment Failures

Symptom: Deployment status shows “Failed” in the portal.

Diagnostic Steps:

Check device is connected: Deployment can only succeed when the device is online and connected.

Check recipe validity: Ensure the recipe JSON/YAML is valid. Common errors: missing commas, wrong indentation, invalid S3 URI paths.

Check artifact availability: The component zip must be uploaded before creating the deployment.

Check disk space: The device needs space to download and extract components. Run df -h on the device.

Check component logs on device: journalctl -u greengrass* -f during deployment shows detailed errors.

Common Deployment Errors:

Error	Cause	Solution
COMPONENT_NOT_FOUND	Artifact not uploaded	Upload component artifact in Package → Components first
INSTALL_FAILED	Missing Python dependency	Check recipe Install lifecycle — ensure pip packages are available
TIMEOUT	Device went offline during deploy	Ensure stable internet, retry deployment
PERMISSION_DENIED	Script needs root access	Add “RequiresPrivilege”: true to recipe lifecycle

No Telemetry Data appearing

Symptom: Device is connected, deployment succeeded, but no data appears in Live Data.

Diagnostic Steps:

Verify component is running: On the device, check if your component process is alive: ps aux | grep example_publisher

Check IPC topic: Your component must publish to iotc/rpt/d2gg/sub (the topic the SDK listens on). Verify the topic name in your code.

Check JSON format: The telemetry JSON must match the expected format: [{"uniqueId": "device-id", "time": "ISO8601", "data": {"attributeName": value}}]

Check attribute names: Attribute names in your telemetry JSON must EXACTLY match the attribute names defined in the template. Case-sensitive.

Check the SDK component: Verify com.iotconnect.sdk2 is deployed and running: journalctl | grep iotconnect

STM32 Specific Issues

Symptom: Installer fails on STM32MP boards with compilation errors or missing tools.

Root Cause: STM32MP factory images do not include the development tools needed to compile Python packages (like awscli / awsiotsdk) from source.

Solution:

You MUST flash the OpenSTLinux Starter Package before running the /IOTCONNECT™ installer. This provides the full development environment including gcc, make, and Python headers.

Tested version: OpenSTLinux 6.0.0 (5.0.3-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06)

Flashing options: Use STM32CubeProgrammer (official, slower) or create_sdcard_from_flashlayout.sh to create an SD image (faster — flash with dd, Rufus, or Balena Etcher).

Resources: ST OpenSTLinux Starter Packages →

Clean Reinstall

If you need to start fresh (name change, new bundle, or corrupted state), run these cleanup commands before re-running the installer:

FAQ

Q: Do I need an AWS account to use Greengrass with /IOTCONNECT™?

No. /IOTCONNECT™ manages all AWS resources (IoT Core, certificates, deployments) on your behalf. You do not need AWS credentials or an AWS Console login.

Q: Can I switch a device from Nucleus Lite to Nucleus Classic?

No. The nucleus type is set at device creation time. Delete the device, do a clean uninstall on the physical device, then create a new device with the other nucleus type.

Q: Can I deploy the same component to multiple devices?

Yes. In the Deployment section, select target type as “Group” or deploy to multiple individual devices. The same package can be deployed to any device using the same template.

Q: How do I update a deployed component?

Create a new version of the component (upload new artifact with incremented version in recipe), update the package, and create a new deployment. The device will automatically replace the old version.

Q: Does the device work offline?

Yes. Once the Nucleus is installed and components are deployed, the device operates fully offline. Telemetry is cached locally and synced when connectivity returns. Components continue executing their logic.

Q: What happens if a deployment fails?

The device rolls back to its previous component state automatically. No partial deployments remain. Fix the issue (recipe, artifact, or device state) and redeploy.

Q: How often does the device sync with the cloud?

Telemetry is sent in near real-time (configurable interval in your component code, typically 10-60 seconds). Device status heartbeats occur every 30 seconds. Deployments are picked up typically within seconds.

of being created.

Best Practices

Security: Never share connection kit bundles. Each device must have unique certificates. Rotate certificates periodically using the portal’s re-download feature.

Versioning: Always increment component version numbers. Never reuse a version number — deployments compare versions to determine what to update.

Monitoring: Use the Diagnostics tab to track connection/disconnection events. Set up event notifications for device disconnect alerts.

Testing: Use a PC or VM with Nucleus Classic for development. Deploy the aws.greengrass.Cli public component for local testing with local-deploy.sh.

Naming: Use consistent naming: site-type-number (e.g., factory1-gateway-001). This makes fleet management easier at scale.

Templates: Design templates with all possible attributes upfront. Adding attributes later requires redeployment of components.

Logging: Include proper logging in your components. Use Python’s logging module with timestamps — logs are accessible via journalctl on the device.

Error Handling: Components should gracefully handle sensor failures, network timeouts, and IPC errors. Never let an unhandled exception crash your component.

ⓘ RESOURCES

SDK Repository: github.com/avnet-iotconnect/iotc-python-greengrass-sdk
Demo Components: github.com/avnet-iotconnect/iotc-python-greengrass-demos
Greengrass Lite Source: github.com/aws-greengrass/aws-greengrass-lite
Video Tutorials: Classic Setup | Lite Setup