tursodatabase/turso · error · java.sql.SQLException

Exception while binding blob value at position {position}

Error message

Exception while binding blob value at position {position}

What it means

bindBlob(position, value) throws when the native bind returns a non-zero result code; the dominant cause is an out-of-range parameter position (SQLITE_RANGE). As with text, a null byte[] should be bound with bindNull rather than passed here. Positions are 1-based and bounded by parameterCount().

Source

Thrown at bindings/java/src/main/java/tech/turso/core/TursoStatement.java:210

    }
    return result;
  }

  private native int bindText(long statementPointer, int position, String value)
      throws SQLException;

  /**
   * Binds a blob value to the prepared statement at the specified position.
   *
   * @param position The index of the SQL parameter to be set.
   * @param value The value to bind to the parameter.
   * @return <a href="https://www.sqlite.org/c3ref/c_abort.html">Result Codes</a>
   * @throws SQLException If a database access error occurs.
   */
  public int bindBlob(int position, byte[] value) throws SQLException {
    final int result = bindBlob(statementPointer, position, value);
    if (result != 0) {
      throw new SQLException("Exception while binding blob value at position " + position);
    }
    return result;
  }

  private native int bindBlob(long statementPointer, int position, byte[] value)
      throws SQLException;

  public void bindObject(int parameterIndex, Object x) throws SQLException {
    if (x == null) {
      this.bindNull(parameterIndex);
      return;
    }
    if (x instanceof Byte) {
      this.bindInt(parameterIndex, (Byte) x);
    } else if (x instanceof Short) {
      this.bindInt(parameterIndex, (Short) x);
    } else if (x instanceof Integer) {
      this.bindInt(parameterIndex, (Integer) x);

View on GitHub (pinned to 244cde92a7)

Solutions

1. Use 1-based positions validated against stmt.parameterCount()
2. Use bindNull for absent blobs instead of passing null arrays
3. Keep SQL text and the blob bind calls together

Example fix

// before
stmt.bindBlob(0, data); // throws

// after
if (data == null) {
  stmt.bindNull(1);
} else {
  stmt.bindBlob(1, data); // 1-based
}

int paramCount = stmt.parameterCount();
if (position < 1 || position > paramCount) {
  throw new IllegalArgumentException("bind position must be 1.." + paramCount);
}
if (value == null) {
  stmt.bindNull(position); // null blobs must not go through bindBlob
} else {
  stmt.bindBlob(position, value);
}

try {
  stmt.bindBlob(position, value);
} catch (SQLException e) {
  throw new IllegalArgumentException(
      "bind failed for position " + position + " (1-based, max " + safeParamCount(stmt) + ")", e);
}

When it happens

Trigger: bindBlob(0, bytes) or a position above the placeholder count; binding a null array instead of using bindNull; binding on a finalized statement.

Common situations: 0-based positions from ported code; optional binary fields forwarded without a null check; SQL edits changing the placeholder count.

Related errors

• Exception while binding NULL value at position {position}
• Exception while binding long value at position {position}
• Exception while binding double value at position {position}
• Exception while binding text value at position {position}
• Unsupported object type in bindObject: {className}

AI-assisted analysis of tursodatabase/turso@244cde92a7 (2026-08-20). Data as JSON: /api/errors/02be165242c276eb. Report an issue: GitHub.