prestodb/presto · error · PinotException

PINOT_UNABLE_TO_FIND_INSTANCE

PINOT_UNABLE_TO_FIND_INSTANCE

Error message

Error when fetching instance configs for %s

What it means

Thrown when fetching a Pinot instance's configuration JSON from the controller (GET on the instance API) fails for any reason. The connector needs the instance config (e.g. server ports) to talk to a Pinot server, so any HTTP/parse failure becomes PINOT_UNABLE_TO_FIND_INSTANCE.

Source

Thrown at presto-pinot-toolkit/src/main/java/com/facebook/presto/pinot/PinotClusterInfoFetcher.java:607

        {
            return tags;
        }

        @JsonProperty
        public List<String> getPools()
        {
            return pools;
        }
    }

    public Instance getInstance(String instanceName)
    {
        try {
            String responseBody = sendHttpGetToController(String.format(INSTANCE_API_TEMPLATE, instanceName));
            return instanceJsonCodec.fromJson(responseBody);
        }
        catch (Exception throwable) {
            throw new PinotException(PINOT_UNABLE_TO_FIND_INSTANCE, Optional.empty(), "Error when fetching instance configs for " + instanceName, throwable);
        }
    }

    // Fetch grpc port from Pinot instance config.
    public int getGrpcPort(String serverInstance)
    {
        try {
            return instanceConfigCache.get(serverInstance).getGrpcPort();
        }
        catch (ExecutionException e) {
            Throwable cause = e.getCause();
            if (cause instanceof PinotException) {
                throw (PinotException) cause;
            }
            throw new PinotException(
                    PINOT_UNABLE_TO_FIND_INSTANCE,
                    Optional.empty(),
                    "Error when getting instance config for " + serverInstance,

View on GitHub (pinned to 55bb57d202)

Solutions

1. Check the cause in logs: 404 means the instance no longer exists in Pinot — refresh routing/instance caches or restart the query
2. Verify the controller is reachable with curl http://<controller>/v2/instances
3. Confirm the instance still exists in ZooKeeper (Helix) and Pinot cluster is healthy
4. Clear stale Presto caches (instance config cache) by restarting the connector/coordinator

// Verify the instance exists on the controller
curl -sf http://<controller>:9000/v2/instances | jq '.instances'

try {
    Table result = session.execute(...);
} catch (PinotException e) {
    if (e.getMessage().startsWith("Error when fetching instance configs")) {
        // retry after controller recovery; check cause for 404 vs network
    }
    throw e;
}

When it happens

Trigger: sendHttpGetToController(INSTANCE_API_TEMPLATE) throws — 404 for unknown instance, controller unreachable, timeout, or non-parseable instance JSON — inside getInstance.

Common situations: Stale routing table referencing a server instance that was decommissioned; controller restarted with different instance IDs; network/firewall blocking controller access; typo in instance name when using grpc config lookups.

Related errors

• PINOT_HTTP_ERROR
• PINOT_UNEXPECTED_RESPONSE
• PINOT_UNCLASSIFIED_ERROR
• PINOT_UNSUPPORTED_COLUMN_TYPE
• PINOT_UNEXPECTED_RESPONSE

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