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-Optionsblocking embedding. - CSP
frame-ancestorsrestrictions. - 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: DENYX-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.
Support
SUBMISSION | Checklist before uploading a game
STANDARDS | Developer Content Standards
ASSETS | How can I safely use third-party assets (art, music, code) in my game?
TOOLS | Can developers use AI tools when building games?
DOCUMENTATION | What documentation must developers follow?
Comments
0 comments
Please sign in to leave a comment.