prestodb/presto · error · RedirectException

Desktop Browser is not available. Make sure your Java proces

Error message

Desktop Browser is not available. Make sure your Java process is not in headless mode (-Djava.awt.headless=false)

What it means

DesktopBrowserRedirectHandler handles external-authentication redirects by opening the authorization URI in the local desktop browser via java.awt.Desktop. If no desktop is supported or BROWSE is unsupported (typical on servers/headless JVMs), it throws this RedirectException so the external authentication flow cannot proceed.

Source

Thrown at presto-client/src/main/java/com/facebook/presto/client/auth/external/DesktopBrowserRedirectHandler.java:31

 */
package com.facebook.presto.client.auth.external;

import java.io.IOException;
import java.net.URI;

import static java.awt.Desktop.Action.BROWSE;
import static java.awt.Desktop.getDesktop;
import static java.awt.Desktop.isDesktopSupported;

public final class DesktopBrowserRedirectHandler
        implements RedirectHandler
{
    @Override
    public void redirectTo(URI uri)
            throws RedirectException
    {
        if (!isDesktopSupported() || !getDesktop().isSupported(BROWSE)) {
            throw new RedirectException("Desktop Browser is not available. Make sure your Java process is not in headless mode (-Djava.awt.headless=false)");
        }

        try {
            getDesktop().browse(uri);
        }
        catch (IOException e) {
            throw new RedirectException("Failed to redirect", e);
        }
    }
}

View on GitHub (pinned to 55bb57d202)

Solutions

Run the client on a workstation with a desktop environment and a default browser, ensuring the JVM is not headless (-Djava.awt.headless=false).
Use an alternative redirect handler that does not require a desktop browser (e.g. a handler that prints the URI for manual opening, or token-based authentication).
If X11 forwarding is intended, connect with ssh -X/-Y and verify DISPLAY is set.
Pre-authorize out-of-band (service account, basic/Kerberos auth) to avoid the external-auth browser flow entirely.

Example fix

// before
java -jar presto-cli ... # headless container
// after
java -Djava.awt.headless=false -jar presto-cli ...   # run on a desktop machine with a browser

Defensive patterns

Strategy: fallback

Validate before calling

boolean desktopBrowserAvailable = java.awt.Desktop.isDesktopSupported()
    && java.awt.Desktop.getDesktop().isSupported(java.awt.Desktop.Action.BROWSE);
if (!desktopBrowserAvailable) {
    System.out.println("Open this URL manually: " + authUri);
}

Type guard

boolean canBrowse(URI uri) {
    return java.awt.Desktop.isDesktopSupported()
        && java.awt.Desktop.getDesktop().isSupported(java.awt.Desktop.Action.BROWSE);
}

Try / catch

try {
    handler.redirectTo(uri);
} catch (RedirectException e) {
    // fallback: print URL for manual browser opening or switch auth method
    System.out.println("Open manually: " + uri);
}

Prevention

Run interactive external auth only on desktop machines with a default browser.
Do not run the CLI in headless containers/CI for external authentication; use token or basic auth there.
Start the JVM with -Djava.awt.headless=false when a display is available.
For remote servers, use SSH port forwarding plus a local browser or copy the auth URL manually.

When it happens

Trigger: Running external authentication (e.g. Presto CLI with an external authenticator) on a JVM started with java.awt.headless=true, or on a machine with no display/no desktop browser, then ExternalAuthenticator calls redirectTo(uri) and isDesktopSupported()/Desktop.isSupported(BROWSE) returns false.

Common situations: Running the Presto CLI inside a Docker container, CI job, SSH session without X11 forwarding, or any server-side Java process where AWT is headless and no browser exists.

Related errors

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/3509ff4d4e8bcdd9. Report an issue: GitHub.