Instant Games

Debugging Tool

Updated: Jun 28, 2026
Copy for LLM
The Instant Games platform includes a built-in debugging tool that gives you a JavaScript console and overlay view inspector directly inside your game. This is especially useful for Zero Permissions development, where overlay views render inside Meta-controlled iframes that are not directly inspectable through standard browser DevTools.

Requirements

Before you can use the debugging tool, make sure both of the following are true:
  • SDK loaded via script tag. Your game must import the Instant Games SDK using a <script> tag in index.html. If you load the SDK asynchronously via JavaScript (for example, by dynamically creating a script element), debug mode will not activate.
  • Not using the embedded player. Debug mode is currently incompatible with the embedded player used for local development. Use it in the regular Facebook player instead.

Enabling debug mode

  1. Go to developers.facebook.com and open your app.
  2. Navigate to the Web Hosting tab under Instant Games.
  3. Find the Debug Mode toggle at the top of the page and switch it on.
Enabling debug mode in App Dashboard
Debug mode is enabled per-app, not per-bundle. Once enabled, it applies to all test sessions launched by developers with access to the app.

Using the debugging tool

Once debug mode is enabled:
  1. Open your game on Facebook (web or mobile).
  2. Look for the debug icon (a wrench and screwdriver symbol) in the bottom-right corner of the game viewport.
  3. Tap or click the icon to open the debugging interface.
Opening debug mode in-game

JavaScript console

The JS Console tab provides a browser-like console for interacting with your game at runtime. You can:
  • Execute JavaScript expressions against your game’s context.
  • Inspect SDK state (e.g., FBInstant.player.getID(), FBInstant.context.getID()).
  • View console output (console.log, console.error, and so on) from your game code.

Overlay views inspector

The Overlay Views tab lets you inspect and interact with your overlay views:
  • View the rendered HTML inside each overlay iframe.
  • Check the current state and data bound to each overlay.
  • Debug layout and styling issues that are difficult to diagnose through the game UI alone.

Troubleshooting

The debug icon does not appear in-game:
  • Verify that debug mode is toggled on in the App Dashboard (see above).
  • Confirm that you are logged into Facebook with the same account you use on developers.facebook.com. If you use a Meta Business Suite account on the developer site, use that same account to play the game.
  • Make sure your SDK is loaded via a <script> tag, not injected dynamically.
  • If you recently enabled debug mode, try refreshing the game or starting a new session.

Next steps

  • Testing — Full guide to testing Zero Permissions games in regular and local environments.
  • Overlay View Components — Reference for the XML components used in overlay views.
  • Overlay Preview Tool — Build and test overlay views interactively without deploying a bundle.