Why does my SubViewport show a black rectangle in Godot 4?

A black SubViewport usually means the viewport has no content being rendered into it, or the update mode is set to ONCE or DISABLED. Ensure the SubViewport has a non-zero size, contains visible child nodes (like a Camera2D or Camera3D), and that render_target_update_mode is set to ALWAYS or WHEN_VISIBLE.

How do I display a SubViewport on a sprite in Godot 4?

Use a SubViewportContainer as the parent of the SubViewport, or get the viewport texture via get_texture() and assign it to a Sprite2D or TextureRect. The SubViewportContainer approach handles sizing and updates automatically.

Why is my SubViewport transparent instead of showing content?

Check that transparent_bg is set to false (unless you intentionally want transparency). Also verify the SubViewport has a Camera node as a child, or that the content fits within the SubViewport's size. Without a camera, the viewport may not render any content.

Fix: Godot SubViewport Rendering as Black or Transparent

Quick answer: A black SubViewport usually means the viewport has no content being rendered into it, or the update mode is set to ONCE or DISABLED.

Here is how to fix Godot SubViewport rendering black transparent. SubViewports in Godot 4 are powerful tools for rendering minimap cameras, picture-in-picture views, portals, and render-to-texture effects. But getting them to actually display something can be frustrating. You add a SubViewport to your scene, set it up with content, and all you see is a black rectangle — or worse, nothing at all. This guide covers the most common reasons SubViewports fail to render and how to fix each one.

The Symptom

You have a SubViewport in your scene tree with child nodes that should be visible — sprites, meshes, a camera. But when you run the project, the area where the SubViewport content should appear shows as a solid black rectangle, a transparent gap, or simply renders nothing. The SubViewport node exists and is not erroring in the output log, but its visual output is empty.

In the editor preview, the SubViewport might show a checkerboard pattern (indicating transparency) or a solid color. At runtime, a TextureRect or Sprite2D displaying the SubViewport's texture shows black. If you are using a SubViewportContainer, the container area appears empty.

Sometimes the SubViewport works once on the first frame but then freezes or goes black, which indicates an update mode issue rather than a setup issue.

What Causes This

SubViewport rendering failures typically come from one of four configuration mistakes:

Zero viewport size — A SubViewport with a width or height of 0 has no render target to draw into. Godot silently produces nothing. This is the most common cause and the easiest to miss because the size defaults to 0x0 when you first add the node.
Wrong update mode — The render_target_update_mode property controls when the SubViewport re-renders. If set to ONCE, it only renders a single frame. If set to DISABLED, it never renders. For continuous rendering (like a minimap), you need ALWAYS or WHEN_VISIBLE.
No camera in the SubViewport — For 3D content, a SubViewport needs its own Camera3D to define the view. Without one, there is nothing to render from. For 2D content, a Camera2D is optional but may be needed if your content is not at the origin.
transparent_bg misconfiguration — If transparent_bg is true but the node displaying the texture does not support or expect transparency, the content appears invisible against a matching background.

The Fix

Step 1: Set the SubViewport size. Select the SubViewport node and set its Size property to a non-zero value. A common choice is 512x512 for a minimap or the same resolution as your main viewport for a portal effect.

# Set SubViewport size in code
extends Node2D

@onready var sub_viewport = $SubViewport

func _ready():
    sub_viewport.size = Vector2i(512, 512)

Step 2: Set the update mode to ALWAYS. In the SubViewport inspector, set Render Target → Update Mode to Always. This ensures the viewport re-renders every frame. Use When Visible for performance optimization once everything is working.

# Set update mode in code
func _ready():
    sub_viewport.render_target_update_mode = SubViewport.UPDATE_ALWAYS

Step 3: Add a camera. For 3D SubViewports, add a Camera3D as a child. For 2D SubViewports, add a Camera2D if your content is not positioned at the world origin. Make sure the camera is set as the current camera within the SubViewport.

# Scene tree structure for a working minimap:
# SubViewportContainer
#   SubViewport (size: 256x256, update_mode: ALWAYS)
#     Camera2D (current: true, zoom: Vector2(0.25, 0.25))
#     RemoteTransform2D (targeting player)

# Make camera current within its SubViewport
extends Camera2D

func _ready():
    make_current()

Step 4: Display the SubViewport texture correctly. The simplest approach is to use a SubViewportContainer as the parent of the SubViewport. The container automatically sizes itself and displays the viewport content. Alternatively, you can manually assign the texture:

# Method 1: SubViewportContainer (recommended)
# Just parent the SubViewport to a SubViewportContainer.
# The container handles everything automatically.

# Method 2: Manual texture assignment
extends Sprite2D

@onready var sub_viewport = $"../SubViewport"

func _ready():
    # Wait one frame for the viewport to initialize
    await get_tree().process_frame
    texture = sub_viewport.get_texture()

Note the await get_tree().process_frame in the manual approach. The SubViewport texture may not be ready on the first frame, so waiting one frame before assigning it avoids a race condition that can produce a black texture.

Why This Works

A SubViewport is essentially a self-contained rendering context. It needs three things to produce output: a render target (defined by its size), content (child nodes to render, with a camera for 3D), and an update schedule (when to re-render). Missing any one of these produces black or empty output.

The SubViewportContainer simplifies the pipeline because it handles the connection between the SubViewport's rendered texture and the display surface automatically. Without it, you have to manually retrieve the texture with get_texture() and handle timing carefully.

The transparent_bg setting controls whether the clear color of the SubViewport is transparent or opaque black. For most use cases (minimaps, portals, render-to-texture), you want this false so the viewport has a solid background. Set it to true only when you need to composite the SubViewport content over other visuals with alpha blending.

"SubViewport size was 0x0. That was it. Twenty minutes of debugging for a default value I never thought to check."

Related Issues

If your SubViewport renders content but the colors are wrong or the screen is pink, the issue may be a shader error within the SubViewport. See Fix: Godot Shader Causing Pink/Magenta Screen.

For flickering or tearing in SubViewport content, check Fix: Screen Flickering or Tearing in Godot for frame pacing solutions that also apply to SubViewport update timing.

If 3D models inside your SubViewport appear inside out, the normals issue applies within SubViewports too. See Fix: Godot 3D Models Appearing Inside Out or Invisible.

Size it. Update it. Camera it. Done.