{"record":{"id":"8c000d5bb9810c81","repo":"apache/seatunnel","slug":"sqlite-database-file-not-found-sqlitepath","errorCode":null,"errorMessage":"SQLite database file not found: ${sqlitePath}","messagePattern":"SQLite database file not found: (.+?)","errorType":"exception","errorClass":"SQLException","httpStatus":null,"severity":"error","filePath":"seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/command/db/EdgeAgentDbConnection.java","lineNumber":38,"sourceCode":"import org.apache.seatunnel.edge.agent.starter.wal.sqlite.SqliteSchemaBootstrap;\n\nimport java.nio.file.Files;\nimport java.nio.file.Path;\nimport java.sql.Connection;\nimport java.sql.DriverManager;\nimport java.sql.SQLException;\n\npublic class EdgeAgentDbConnection implements AutoCloseable {\n\n    private final Connection connection;\n\n    private EdgeAgentDbConnection(Connection connection) {\n        this.connection = connection;\n    }\n\n    public static EdgeAgentDbConnection openReadOnly(Path sqlitePath) throws SQLException {\n        if (!Files.isRegularFile(sqlitePath)) {\n            throw new SQLException(\"SQLite database file not found: \" + sqlitePath);\n        }\n        openMaintenanceConnection(sqlitePath).close();\n        Connection connection =\n                DriverManager.getConnection(\n                        \"jdbc:sqlite:\" + sqlitePath.toAbsolutePath().normalize());\n        try (java.sql.Statement statement = connection.createStatement()) {\n            statement.execute(\"PRAGMA query_only = ON\");\n        }\n        return new EdgeAgentDbConnection(connection);\n    }\n\n    public static EdgeAgentDbConnection openReadWrite(Path sqlitePath) throws SQLException {\n        return new EdgeAgentDbConnection(openMaintenanceConnection(sqlitePath));\n    }\n\n    private static Connection openMaintenanceConnection(Path sqlitePath) throws SQLException {\n        Path prepared = SqliteSchemaBootstrap.prepareSqlitePath(sqlitePath);\n        Connection connection =","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/command/db/EdgeAgentDbConnection.java#L20-L56","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Start the agent once so it creates the SQLite database at the configured path, then retry the db command.","Verify the configured data directory (paths.getSqlitePath()) and correct any path override so it points at the real agent data dir.","Check the file exists (ls -l <sqlitePath>); if missing, restore from backup or let the agent recreate it.","Confirm the volume/mount containing the database is attached before running maintenance commands."],"exampleFix":"# before (running db tool against nonexistent db)\nagent db info\n# Error: SQLite database file not found: /var/lib/edge-agent/agent.db\n# after\nagent start   # creates the database\nagent db info","handlingStrategy":"try-catch","validationCode":"import os\nif not os.path.isfile(sqlite_path):\n    raise FileNotFoundError(f'Start the agent first; no database at {sqlite_path}')","typeGuard":"function isRegularFile(p) {\n  try { return require('fs').statSync(p).isFile(); } catch { return false; }\n}\nif (!isRegularFile(sqlitePath)) throw new Error('SQLite database file not found: ' + sqlitePath);","tryCatchPattern":"try (EdgeAgentDbConnection db = EdgeAgentDbConnection.openReadOnly(paths.getSqlitePath())) {\n    // ...\n} catch (SQLException e) {\n    if (e.getMessage().startsWith(\"SQLite database file not found\")) {\n        System.err.println(\"Agent has not initialized its database; start the agent first or fix the data dir.\");\n    } else { throw e; }\n}","preventionTips":["Start the agent at least once before running offline db maintenance commands.","Verify the configured data dir / sqlitePath in agent config before invoking db commands.","In containers, ensure the data volume is mounted and persistent across restarts.","Use Files.isRegularFile as a preflight check in automation scripts."],"tags":["sqlite","database","file-not-found","cli"],"backgroundTag":"file-not-found","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}