iFrame | Game doesn't work in iFrame on Kongregate – Developer Portal - Support

Best practice is always to verify that your game works in 'Preview' mode on Kongregate before submitting it for publishing. If your game loads locally but does not display correctly on Kongregate, the issue is often related to browser security settings, embedding restrictions, or game configuration. Below are the most common causes and solutions.

In practice most Kongregate iframe issues tend to be:

X-Frame-Options blocking embedding.
CSP frame-ancestors restrictions.
Mixed HTTP/HTTPS content.
CORS restrictions on assets or APIs.
Third-party cookie/storage dependencies.

My game works when opened directly, but shows a blank screen on Kongregate.

Possible Causes

Your game is blocking embedding in an iFrame

Some web servers send security headers that prevent websites from embedding content in an iFrame.

Common headers that can cause this include:

X-Frame-Options: DENY
X-Frame-Options: SAMEORIGIN
Content Security Policy (frame-ancestors) restrictions

Solution

Ensure your server allows your game to be embedded by third-party sites such as Kongregate.

For example, avoid:

X-Frame-Options: DENY

and review any Content Security Policy rules that restrict embedding.

My Scratch game refuses to connect on Kongregate

This is an example of the issue mentioned above. The iFrame upload string fails because Scratch blocks direct embedding via X-Frame-Options and requires a specific /embed URL format.

Solution

To resolve this, convert the project into a standalone HTML file using a tool like TurboWarp and upload it directly to Kongregate as an HTML5 package. As always, please test the game in preview mode in the Developer Portal, and verify the game works before submitting.

I see an error about "Refused to frame" in my browser console.

Cause

Your server is explicitly preventing Kongregate from displaying the game in an iFrame.

Solution

Check your web server configuration, CDN configuration, and any security middleware that may be adding restrictive frame headers.

The game loads but some assets are missing.

Possible Causes

Incorrect asset paths
Relative URLs that resolve incorrectly when embedded
Missing files in the upload package
Cross-origin (CORS) restrictions

Solution

Verify that:

All assets are included in your build.
Asset URLs resolve correctly when loaded from Kongregate.
Your browser's Developer Tools Network tab shows successful asset requests.
Any external resources allow cross-origin access.

The game works in one browser but not another.

Possible Causes

Browser-specific compatibility issues
Unsupported APIs
Security restrictions
Third-party cookie dependencies

Solution

Test your game in:

Chrome
Firefox
Edge
Safari (if applicable)

Review browser console errors for clues.

My game depends on third-party cookies or local storage.

Cause

Modern browsers increasingly restrict third-party cookies and storage access inside embedded content.

Solution

Avoid relying on third-party cookies for core gameplay functionality.

Where possible:

Use first-party storage mechanisms.
Store game data through your own backend.
Gracefully handle storage restrictions.

Audio does not start automatically.

Cause

Most browsers block autoplay audio until the player interacts with the page.

Solution

Start audio only after a user action such as:

Clicking a Start button
Pressing Play
Interacting with the game canvas

Fullscreen mode is not working.

Cause

Fullscreen APIs may require user interaction and proper implementation.

Solution

Trigger fullscreen only in response to a player action and verify that your implementation follows current browser requirements.

My game is making HTTP requests that fail.

Possible Causes

Mixed content (HTTP resources loaded from HTTPS pages)
CORS restrictions
Blocked third-party services

Solution

Ensure all resources are served over HTTPS and that any APIs or services your game depends on permit requests from your game origin.

The game appears cropped or incorrectly sized.

Cause

Responsive sizing issues or fixed-width layouts may not adapt correctly to the Kongregate game container.

Solution

Verify that:

Your game supports responsive layouts where possible.
Canvas resizing is handled correctly.
UI elements adapt to different browser sizes and aspect ratios.

The game hangs during loading.

Possible Causes

JavaScript errors
Missing assets
Network failures
Infinite loading loops

Solution

Open your browser's Developer Tools and check:

Console errors
Failed network requests
JavaScript exceptions

These logs often identify the exact asset or script causing the issue.

How can I troubleshoot submission issues?

We recommend the following process:

Test your production build outside Kongregate.
Test the same build embedded in a local iFrame.
Open Developer Tools and review Console and Network tabs.
Verify there are no frame-blocking security headers.
Confirm all assets load successfully over HTTPS.
Test in multiple browsers.
Retest after making changes before submitting a new build.

If you continue experiencing issues, include any browser console errors, network failures, and screenshots when contacting Kongregate Support (developers@kongregate.com). The more diagnostic information provided, the faster we can help identify the root cause.