apache/seatunnel · error · SQLException

SQLite database file not found

Error message

SQLite database file not found: ${sqlitePath}

What it means

EdgeAgentDbConnection.openReadOnly checks that the SQLite file exists as a regular file before opening any JDBC connection, throwing SQLException naming the missing path if not. The CLI db commands are offline maintenance tools and never create the database — a missing file is a hard error rather than being auto-created (which jdbc:sqlite would otherwise do).

Solutions

1. Start the agent once so it creates the SQLite database at the configured path, then retry the db command.
2. Verify the configured data directory (paths.getSqlitePath()) and correct any path override so it points at the real agent data dir.
3. Check the file exists (ls -l <sqlitePath>); if missing, restore from backup or let the agent recreate it.
4. Confirm the volume/mount containing the database is attached before running maintenance commands.

Example fix

# before (running db tool against nonexistent db)
agent db info
# Error: SQLite database file not found: /var/lib/edge-agent/agent.db
# after
agent start   # creates the database
agent db info

import os
if not os.path.isfile(sqlite_path):
    raise FileNotFoundError(f'Start the agent first; no database at {sqlite_path}')

function isRegularFile(p) {
  try { return require('fs').statSync(p).isFile(); } catch { return false; }
}
if (!isRegularFile(sqlitePath)) throw new Error('SQLite database file not found: ' + sqlitePath);

try (EdgeAgentDbConnection db = EdgeAgentDbConnection.openReadOnly(paths.getSqlitePath())) {
    // ...
} catch (SQLException e) {
    if (e.getMessage().startsWith("SQLite database file not found")) {
        System.err.println("Agent has not initialized its database; start the agent first or fix the data dir.");
    } else { throw e; }
}

When it happens

Trigger: Running `agent db info` or `wal-list` before the agent has ever started and created the SQLite file; pointing the config at the wrong data directory; the database file was deleted or its volume is not mounted.

Common situations: Fresh environments where the agent was never run; wrong home/data directory in containers; deleted or missing data volume; typo'd path overrides in config.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Agent config file not found
• Agent is running (pid file ); stop the agent before write…
• AmazonDocumentDB TLS CA bundle is not a readable file:
• API-09
• clickhouse local file not exists

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

Appendix: source

Thrown at seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/command/db/EdgeAgentDbConnection.java:38

import org.apache.seatunnel.edge.agent.starter.wal.sqlite.SqliteSchemaBootstrap;

import java.nio.file.Files;
import java.nio.file.Path;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

public class EdgeAgentDbConnection implements AutoCloseable {

    private final Connection connection;

    private EdgeAgentDbConnection(Connection connection) {
        this.connection = connection;
    }

    public static EdgeAgentDbConnection openReadOnly(Path sqlitePath) throws SQLException {
        if (!Files.isRegularFile(sqlitePath)) {
            throw new SQLException("SQLite database file not found: " + sqlitePath);
        }
        openMaintenanceConnection(sqlitePath).close();
        Connection connection =
                DriverManager.getConnection(
                        "jdbc:sqlite:" + sqlitePath.toAbsolutePath().normalize());
        try (java.sql.Statement statement = connection.createStatement()) {
            statement.execute("PRAGMA query_only = ON");
        }
        return new EdgeAgentDbConnection(connection);
    }

    public static EdgeAgentDbConnection openReadWrite(Path sqlitePath) throws SQLException {
        return new EdgeAgentDbConnection(openMaintenanceConnection(sqlitePath));
    }

    private static Connection openMaintenanceConnection(Path sqlitePath) throws SQLException {
        Path prepared = SqliteSchemaBootstrap.prepareSqlitePath(sqlitePath);
        Connection connection =

View on GitHub (pinned to cf67b549a7)