tursodatabase/turso · error · java.sql.SQLException

Exception while binding text value at position {position}

Error message

Exception while binding text value at position {position}

What it means

bindText(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). A secondary cause specific to text is passing a null String where the native layer expects a valid string reference — nulls must go through bindNull instead. Positions are 1-based and bounded by parameterCount().

Source

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

    }
    return result;
  }

  private native int bindDouble(long statementPointer, int position, double value)
      throws SQLException;

  /**
   * Binds a text 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 bindText(int position, String value) throws SQLException {
    final int result = bindText(statementPointer, position, value);
    if (result != 0) {
      throw new SQLException("Exception while binding text value at position " + position);
    }
    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) {

View on GitHub (pinned to 244cde92a7)

Solutions

1. Use 1-based positions validated against stmt.parameterCount()
2. Route null strings through bindNull(position), never bindText
3. Keep SQL and binds adjacent so placeholder edits propagate

Example fix

// before
stmt.bindText(1, maybeName); // throws when maybeName == null

// after
if (maybeName == null) {
  stmt.bindNull(1);
} else {
  stmt.bindText(1, maybeName);
}

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

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

When it happens

Trigger: bindText(0, s) or a position above the placeholder count; calling bindText(i, null) instead of bindNull(i); binding on a statement already closed.

Common situations: 0-based positions; optional string parameters 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 blob 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/8d231c42f88cff78. Report an issue: GitHub.