Frequently Asked Questions

April 27, 2026 ยท View on GitHub

Topics:

Where should I start?

If you're just getting started, make sure you build this SDK before building and running the Certificate and Key File Connect Sample.

Where can I get the API documentation?

Load the library in XCode and then go to Product > Build Documentation.

How do I enable logging?

try? Logger.initialize(target: .standardOutput, level: .debug)

You can also enable CloudWatch logging for AWS IoT, which provides you with additional information that's not available on the client-side SDK.

I am getting OSStatus -34018 when adding a certificate

The errSecMissingEntitlement OSStatus error indicates that a required entitlement is missing. For more information, see errSecMissingEntitlement on Apple's developer website. You must provide entitlements to the app or binary you're building and running using the SDK to allow it permission to access the Mac Keychain on the device. This entitlement can't be given directly to the SDK library and must be provided to the application being built using the SDK library.

I keep getting AWS_ERROR_MQTT_UNEXPECTED_HANGUP

This error is most likely due to a policy issue. Try using a super permissive IAM policy called AWSIOTFullAccess:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:*"
            ],
            "Resource": "*"
        }
    ]
}

After you resolve this error, make sure to only allow the actions and resources that you need. To learn more about IAM policies for AWS IoT, see How AWS IoT works with IAM in the AWS IoT Core Developer Guide.

What is Error Code 5153 (AWS_ERROR_MQTT5_USER_REQUESTED_STOP)?

Error code 5153 (AWS_ERROR_MQTT5_USER_REQUESTED_STOP) is not an error. It is an informational status code indicating that the MQTT5 client connection was closed because your application called client.stop().

The SDK reports all connection shutdown reasons through error codes, including intentional disconnections. When you see this in your logs:

Mqtt5 client connection interrupted by user request.

It means the disconnect was initiated by your code, not by a network failure or broker rejection. This is the expected behavior when gracefully shutting down a connection.

What certificates do I need?

  • You can download pre-generated certificates from the AWS Management Console (this is the simplest and is recommended for testing).
  • You can also generate your own certificates to fit your specific use case. For more information, see X.509 client certificates in the AWS IoT Core Developer Guide and AWS IoT device provisioning in the AWS IoT Device Management Workshop.
  • Certificates required to run the samples
    • Device certificate
      • An intermediate device certificate that is used to generate the key.
      • When using the samples, the certificate can look like this: --cert abcde12345-certificate.pem.crt
    • Key files
      • You must generated and downloaded the private and public keys that are used to verify that communications are coming from you.
      • When using the samples, you only need the private key. For example: --key abcde12345-private.pem.key
    • Root CA certificates
      • Download the root CA certificate file that corresponds to the type of data endpoint and cipher suite you're using (usually Amazon Root CA 1).
      • Root CA certificates are generated and provided by Amazon. You can download a certificate from Amazon Trust Service or while getting the other certificates from the AWS Management Console.
      • When using the sample, the certificate can look like this: --ca_file root-CA.crt

If you encounter a "s2n Permission Denied" error, it's likely because you're attempting to use an unsupported platform. s2n-tls is a library for Unix-like platform.

The AWS IoT Device SDK for Swift supports the following platforms:

  • macOS
  • iOS
  • tvOS
  • Linux

Certificate and Private Key Usage Across Different Versions of the SDK on macOS

A certificate and private key pair cannot be shared on a macOS device between aws-iot-device-sdk-swift v0.5.0 and other versions. In the update to v0.5.0 we migrated macOS from using Apple's deprecated Security Framework to SecItem API. In doing so, certificate and private keys are imported in a non-backwards compatible manner into the Apple Keychain.

Manual Publish Acknowledgement and QoS 1 Redelivery

When using manual publish acknowledgement, there are two important behaviors to be aware of regarding QoS 1 message redelivery:

Broker redelivery of unacknowledged publishes

The AWS IoT broker will periodically resend unacknowledged QoS 1 PUBLISH packets. These redeliveries should be treated as duplicates even if the DUP flag in the PUBLISH packet is not set. If the manual publish acknowledgement is not acquired again for a redelivered packet, the acknowledgement will be sent automatically.

Session resumption after disconnect/reconnect

Upon a disconnect and reconnect of the MQTT5 client, if a session is resumed, any previously acquired acknowledgement handle is void. The broker will resend the unacknowledged PUBLISH packet, and the acknowledgement must be reacquired from that resent packet. If the resent packet is not handled for manual acknowledgement, the acknowledgement will be sent automatically.

To learn more about this SDK