What causes "Failed to start metadata sidecar at %s" in prestodb/presto?

Inspect the cause (t) attached to this exception — it shows the actual launch/startup failure

prestodb/presto · critical · PrestoException

NATIVE_EXECUTION_PROCESS_LAUNCH_ERROR

NATIVE_EXECUTION_PROCESS_LAUNCH_ERROR

Error message

Failed to start metadata sidecar at %s

What it means

MetadataSidecarProcess extends the native process launcher; propagateStartFailure converts any Throwable observed while starting the sidecar process into a PrestoException with NATIVE_EXECUTION_PROCESS_LAUNCH_ERROR. Per the comment, this is thrown on the driver side to fail the Spark application rather than triggering executor failover.

Source

Thrown at presto-spark-base/src/main/java/com/facebook/presto/spark/execution/nativeprocess/MetadataSidecarProcess.java:171

                "storage_user_name=" + storageUserName,
                "storage_service_name=" + storageServiceName,
                "experimental.spiller-spill-path=" + configBasePath.resolve("spill").toAbsolutePath());
    }

    private Iterable<String> buildNodeConfigLines()
    {
        return Arrays.asList(
                "node.environment=presto-spark-driver-sidecar",
                "node.internal-address=" + SIDECAR_NODE_INTERNAL_ADDRESS,
                "node.location=presto-spark-driver-sidecar",
                "node.id=" + UUID.randomUUID());
    }

    @Override
    protected RuntimeException propagateStartFailure(Throwable t)
    {
        // Driver-side: fail the Spark application, don't trigger executor failover.
        throw new PrestoException(
                NATIVE_EXECUTION_PROCESS_LAUNCH_ERROR,
                format("Failed to start metadata sidecar at %s", getLocation()),
                t);
    }

    /**
     * Writes config.properties / node.properties into the given directory using the same
     * content {@link #populateConfigurationFiles} writes. Exposed for unit tests that want
     * to verify the file layout without spawning a process.
     */
    void writeConfigsForTest(Path configBasePath)
            throws IOException
    {
        populateConfigurationFiles(configBasePath);
    }
}

View on GitHub (pinned to 55bb57d202)

Solutions

Inspect the cause (t) attached to this exception — it shows the actual launch/startup failure
Verify the sidecar binary path is valid and executable in the Spark driver environment (see resolveProcessWorkingPath)
Check that the sidecar port is free and not blocked by firewall
Confirm native runtime dependencies (shared libraries, temp storage) exist on the driver host

Defensive patterns

Strategy: validation

Validate before calling

File binary = new File(sidecarBinaryPath);
if (!binary.exists() || !binary.canExecute()) {
    throw new IllegalStateException("Sidecar binary missing or not executable: " + sidecarBinaryPath);
}

Try / catch

try {
    sidecarFactory.getOrStart();
} catch (PrestoException e) {
    // inspect e.getCause() for the real launch failure before failing the app
}

Prevention

Verify sidecar binary existence and execute permission on driver hosts before app start
Reserve the sidecar port and check availability during deployment
Bake native runtime dependencies into the driver image

When it happens

Trigger: The metadata sidecar process fails during its startup sequence (process exits early, fails readiness handshake, or start() observes an exception); propagateStartFailure(t) wraps it, formatting the message with the process location.

Common situations: Missing or non-executable sidecar binary, bad sidecar command-line/working directory, port conflicts for the sidecar's HTTP server, missing native runtime dependencies (libraries, temp dirs), or the sidecar crashing at boot.

Related errors

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