Troubleshooting Amazon GameLift Streams

If the IAM role has an explicit "deny-all" policy, you must explicitly list Amazon GameLift Streams as an exception to that policy by adding "gameliftstreams:*" to the NotAction element. For example:

{
    "Sid": "DenyAllExceptListedIfNoMFA",
    "Effect": "Deny",
    "NotAction": [
        "iam:CreateVirtualMFADevice",
        "iam:EnableMFADevice",
        "iam:GetUser",
        "iam:ListMFADevices",
        "iam:ListVirtualMFADevices",
        "iam:ResyncMFADevice",
        "sts:GetSessionToken",        
        "gameliftstreams:*"                    // Add this
    ],
    "Resource": "*",
    "Condition": {
        "BoolIfExists": {"aws:MultiFactorAuthPresent": "false"}
    }
}

For more information, see Identity and Access Management for Amazon GameLift Streams in the Security chapter, and review Troubleshooting access denied error messages in the IAM User Guide.

Run your application on a different machine to verify that it's correctly packaged. This confirms that your application content doesn't contain any hardcoded paths, missing assets, libraries, or binaries that might not work on other devices.

Verify that your application is compatible with Proton. Test your application on a local environment without the Amazon GameLift Streams server to verify that it's compatible with Proton. For instructions, see Testing and troubleshooting compatibility with Proton for Amazon GameLift Streams.

Verify runtime. In the Amazon GameLift Streams application configuration, confirm that the file you specified in the Executable launch path is an executable file or script and is correct for the runtime environment that you selected. Windows applications should have a file type of ".exe", ".bat", or ".cmd" and target either of the Windows or Proton runtimes. Native Linux applications should be executable files that target the Ubuntu 22.04 LTS runtime.

Verify required DLLs. Your Windows application might be missing required DLLs. For example, if your application is a debug build, then it requires the debug version of the Microsoft C and C++ (MSVC) runtime libraries. To resolve this, we recommend that you package your build and DLLs side-by-side. For instructions, refer to Prepare a test machine to run a debug executable by Microsoft.

Use the correct executable. For your application to work correctly with Amazon GameLift Streams, set the application path to the full executable that's located in the Binaries/Win64/ (or similar) subfolder. Unreal Engine produces two executables: a small bootstrap executable at the root of the folder, and a platform target executable in the Binaries/Win64/ subfolder. The bootstrap executable at the root attempts to validate pre-conditions are correct and can create false positives on Amazon GameLift Streams that prevent application launch. If the platform target executable is missing, the application might not have been built correctly. For example, see the following folder structure of a sample Unreal application:

BuildApp
|-> MyUnrealApp.exe
|-> MyUnrealApp
            |-> Binaries
                    |-> Win64
                            |-> MyUnrealApp.exe 

Turn off Unreal Engine Asserts. Disable the check, verify, and ensure macros. They can prevent the application from creating crash dumps. For more information, see Asserts in Unreal Engine documentation.

Your machine might have more powerful hardware than Amazon GameLift Streams. Make sure to test the application on a machine with similar performance to the hardware that Amazon GameLift Streams uses:

This verifies that your application's rendering settings are compatible with the GPU and that the performance meets your expectations.

The problem might be due to your network connection or Amazon GameLift Streams's settings. Try the troubleshooting tips in the Stream connectivity issues section.

For Unreal Engine games, refer to Profiling Unreal Engine performance.

Driver-based caching – This approach is specific to the runtime environment GPU and driver version. This option can be applied to all applications and is therefore the default recommended approach. The steps for this approach will need to be replicated for every GPU/driver combination.

Engine-based caching – This approach enables shader caching through the game engine, if available. It places the burden of creating a pre-baked pipeline state object (PSO) cache on the developer. It also assumes that the engine is capable of handling cache support for different drivers on the same GPU hardware.

Choose the closest AWS Region possible to the end user. High latency from your clients to the Region hosting your stream can impact stream quality. Refer to AWS Regions and streaming locations supported by Amazon GameLift Streams for a list of locations where you can stream from. You can ping AWS console endpoints in the Region to get an approximate latency measurement.

Verify your stream group has capacity for new streams.

Verify that ConnectionTimeoutSeconds is reasonably set to allow end users plenty of time to connect before their web client times out.

Ensure firewalls allow access to UDP port range 33435-33465 to allow streaming from Amazon GameLift Streams. If Amazon GameLift Streams can't reach these ports, it can lead to streaming issues, such as a black or grey screen.

Verify that your internet connection can sustain a connection speed of at least 10 Mbps for a 1080p stream. If you detect network issues while playing on Amazon GameLift Streams, your internet speed might be fluctuating and you might not be getting at least 10 Mbps consistently. Run an internet speed test and continue through the troubleshooting steps.

Use a wired network if possible. When using Wi-Fi, move your device close to your router for stronger signal strength.

If you're using a Wi-Fi router with both 2.4 GHz and 5 GHz bands, try connecting to a different band. If you're unsure how to switch your router to a different band, visit the support pages of the manufacturer or provider of your Wi-Fi router. You can also contact their customer service.

Identify if others on the same network (especially when on home Wi-Fi) are running high-bandwidth applications like video streaming, downloading, online gaming, or backups.

Close other applications on your device that take up bandwidth.

Don't use a VPN or proxy while streaming. They can cause higher latencies and impact gameplay.

Verify you're using Wi-Fi instead of cellular networks when playing on an iPad or iPhone. Using a cellular network can result in connectivity issues.

MacOS users should disable Location Services as it will cause the Wi-Fi to pause from time to time, which will lead to a poor streaming experience.

Test to see if the issue is browser-specifc. Overall, we recommend Google Chrome, Microsoft Edge, or a custom Chromium-based desktop application for the best end-user experience and maximum compatibility, particularly with game controllers.

Log input events sent from client and received by the application to identify where there is an input mismatch in your front end code.

Be sure to check Supported browsers and input for additional information on supported browsers and input devices, including known issues and limitations.

Issue: The Command key on MacOS maps to the Meta key event, which maps to the Windows key on Microsoft Windows. The issue is a bug affecting MacOS browsers when Command and another key are pressed simultaneously, where the Meta key is reset when released but the arrow key is not reset because the browser didn't capture a keyup event for the arrow key, so the Web SDK client won't send a keyup event to the server and the streaming application would still think the key is being pressed.

Solution: If you are not using the Command key, you can filter it out using the Web SDK keyboard filter mechanism (keyboardFilter) found in the Web SDK's InputConfiguration interface.

Issue: When you open certain OS-level UI elements (such as browser menu bars on desktop, or Control Center and Notification Center on iOS), the browser stops firing input events without triggering blur or focus events. This causes the server to continue receiving the last input state. This is a browser-level limitation that cannot be reliably detected.

Solution: Use fullscreen mode on desktop browsers to prevent access to browser menu bars. For iOS users with connected keyboards, we recommend creating a native app wrapper with a web view where the native app can better detect and handle focus loss, explicitly triggering browser window focus and blur events. Alternatively, use front-end HTML or in-game UI elements to inform users that a key is still pressed, and provide information about this iOS limitation.

Issue: Amazon GameLift Streams uses a heuristic to pick whether to transmit mouse events in “relative” or “absolute” mode. In relative mode, new mouse updates are provided as small, incremental differences from the previous update. In absolute mode, the mouse cursor is continually forced to a screen position that is synchronized with the client. When the operating system cursor is visible over the streamed content, the heuristic always picks absolute coordinates. This can cause unexpectedly large movement deltas if your application is expecting small, relative updates.

Solution: If your application expects relative mouse motion (for example, FPS-style camera controls or drag-based interactions), hide the operating system cursor during mouse interactions. For instance, hide the cursor on mouse-down and show it again on mouse-up. This ensures dragging motions use relative coordinates, with absolute position synchronized only when the button is released.

Application is hung or crashed. Refer to the Application issues section for troubleshooting instructions.

Stream group status is not Active. Verify the status of the stream group.

On-demand capacity is taking longer to spin up than the timeout specified by ConnectionTimeoutSeconds in the StartStreamSession API. On the Windows runtime, the on-demand spin up time can take 5 minutes or more.

No available capacity in the streaming location. Verify that your allocated capacity is greater than your in-use capacity, or that you have on-demand capacity that's not in use (allocated capacity is less than always-on capacity plus on-demand capacity). In the console, you can find these values in the list of stream groups or on the stream group detail page. Using the service API, you can find these values using GetStreamGroup. A few scenarios where available capacity is temporarily at zero include the following:

Network conditions are so poor that frames, especially the first frame, are not being sent. Check network conditions between the client and the streaming location and adjust or try a different location.

Placement timeout: Timeout value for Amazon GameLift Streams to find compute resources to host a stream session.

Connection timeout: Timeout value for a client to connect or reconnect to a stream session.

Idle timeout: Maximum time that a stream session can be idle with no user input.

Session length timeout: Maximum time for a stream session.