apache/seatunnel · critical · SQLException

Failed to initialize next_batch_id in edge_agent_meta

Error message

Failed to initialize next_batch_id in edge_agent_meta

What it means

SqliteBatchIdAllocator.allocateNext() reads next_batch_id from the edge_agent_meta table and seeds it from the WAL if missing. This SQLException is thrown when, even after seeding, the value is absent, zero, or negative — meaning the allocator cannot determine a valid starting batch id. It indicates corrupted or uninitializable WAL metadata.

Solutions

1. Check the edge_agent_meta table: ensure a next_batch_id row exists with a value > 0 (SELECT value FROM edge_agent_meta WHERE key='next_batch_id').
2. If the meta row is missing/corrupt, verify the WAL still contains events so seedMetaFromWal can recover the id; restore the WAL file if it was deleted.
3. If no WAL data exists (truly fresh state), re-initialize the agent data directory so the schema/seed path runs cleanly.
4. Ensure the sqlite file is not being modified concurrently by another process holding locks or an old agent instance.

try (Statement st = connection.createStatement(); ResultSet rs = st.executeQuery("SELECT value FROM edge_agent_meta WHERE key='next_batch_id'")) { if (!rs.next() || rs.getLong(1) <= 0) { /* reseed or re-init before allocating */ } }

When it happens

Trigger: Calling allocateNext(connection) when edge_agent_meta has no next_batch_id row and seedMetaFromWal cannot derive a positive id (e.g. empty WAL with no prior batches), or the stored value is <= 0.

Common situations: Fresh agent deployment with a wiped/empty WAL database; manual edits or corruption of the sqlite meta table; a WAL that was truncated externally so seeding finds nothing; an external tool resetting next_batch_id to 0.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Failed to advance next_batch_id
• Failed to append EdgeEvent to WAL: generated id is missing.
• batchId must be positive
• COMMON-17
• COMMON_WRITER_OPERATION_FAILED

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/be0d14b8aaed3543. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/wal/sqlite/SqliteBatchIdAllocator.java:38

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

public class SqliteBatchIdAllocator {

    /**
     * Returns the next batch id and advances the counter. Must run inside an open transaction on
     * {@code connection}.
     */
    public static long allocateNext(Connection connection) throws SQLException {
        Long current = readNextBatchId(connection);
        if (current == null) {
            seedMetaFromWal(connection);
            current = readNextBatchId(connection);
        }
        if (current == null || current <= 0) {
            throw new SQLException("Failed to initialize next_batch_id in edge_agent_meta");
        }
        try (PreparedStatement statement =
                connection.prepareStatement(MetaSqlStatements.UPDATE_VALUE)) {
            statement.setLong(1, current + 1);
            statement.setString(2, MetaSqlStatements.KEY_NEXT_BATCH_ID);
            if (statement.executeUpdate() != 1) {
                throw new SQLException("Failed to advance next_batch_id");
            }
        }
        return current;
    }

    public static Long peekNextBatchId(Connection connection) throws SQLException {
        return readNextBatchId(connection);
    }

    public static void seedMetaFromWal(Connection connection) throws SQLException {
        try (PreparedStatement statement =

View on GitHub (pinned to cf67b549a7)