apache/shardingsphere · error · IllegalStateException

Can not describe portal `%s` before bind

Error message

Can not describe portal `%s` before bind

What it means

Error "Can not describe portal `%s` before bind" thrown in apache/shardingsphere.

Source

Thrown at proxy/frontend/dialect/postgresql/src/main/java/org/apache/shardingsphere/proxy/frontend/postgresql/command/query/extended/Portal.java:128

     */
    public void bind() throws SQLException {
        responseHeader = proxyBackendHandler.execute();
    }
    
    /**
     * Describe portal.
     *
     * @return portal description packet
     * @throws IllegalStateException illegal state exception
     */
    public PostgreSQLPacket describe() {
        if (responseHeader instanceof QueryResponseHeader) {
            return createRowDescriptionPacket((QueryResponseHeader) responseHeader);
        }
        if (responseHeader instanceof UpdateResponseHeader) {
            return PostgreSQLNoDataPacket.getInstance();
        }
        throw new IllegalStateException(String.format("Can not describe portal `%s` before bind", name));
    }
    
    private PostgreSQLRowDescriptionPacket createRowDescriptionPacket(final QueryResponseHeader queryResponseHeader) {
        return new PostgreSQLRowDescriptionPacket(createColumnDescriptions(queryResponseHeader));
    }
    
    private Collection<PostgreSQLColumnDescription> createColumnDescriptions(final QueryResponseHeader queryResponseHeader) {
        Collection<PostgreSQLColumnDescription> result = new LinkedList<>();
        int columnIndex = 0;
        for (QueryHeader each : queryResponseHeader.getQueryHeaders()) {
            PostgreSQLValueFormat valueFormat = determineValueFormat(columnIndex);
            int currentColumnIndex = ++columnIndex;
            Integer typeOID = (Integer) each.getProtocolAttributes().get(PostgreSQLQueryHeaderBuilder.TYPE_OID);
            result.add(PostgreSQLValueFormat.TEXT == valueFormat && null != typeOID
                    ? new PostgreSQLColumnDescription(each.getColumnLabel(), currentColumnIndex, typeOID, each.getColumnLength(), valueFormat.getCode())
                    : new PostgreSQLColumnDescription(each.getColumnLabel(), currentColumnIndex, each.getColumnType(), each.getColumnLength(), each.getColumnTypeName(), valueFormat.getCode()));
        }
        return result;

View on GitHub (pinned to e952770a21)

Solutions

1. Issue a Bind for the portal before sending Describe.
2. Check the client driver sequence: Parse, Bind, then Describe/Execute.
3. Recreate the prepared statement and portal if the protocol state is lost.

When it happens

Trigger: A Describe (portal) message arrives for a portal that has not been bound yet.

Common situations: Non-compliant clients or connection poolers skipping the Bind step of the extended query protocol.

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/926cf21afc16f5e6. Report an issue: GitHub.